devframe 0.8.2 → 0.9.0-beta.10

package/dist/{index-Dbw1p5ch.d.mts → index-tdrk1bzV.d.mts}

@@ -1,5 +1,4 @@
-import { C as RpcFunctionType, S as RpcFunctionSetupResult, T as RpcReturnSchema, _ as RpcFunctionDefinition, i as RpcArgsSchema, v as RpcFunctionDefinitionAny, w as RpcFunctionsCollector } from "./types-CnJSgRVa.mjs";
-import { a as getDefinitionsWithDumps$1, c as StaticRpcDumpManifest$1, d as StaticRpcDumpManifestValue$1, f as StaticRpcDumpSerialization$1, i as dumpFunctions$1, l as StaticRpcDumpManifestQueryEntry$1, n as serializeDumpError$1, o as StaticRpcDumpCollection$1, p as collectStaticRpcDump$1, r as createClientFromDump$1, s as StaticRpcDumpFile$1, t as reviveDumpError$1, u as StaticRpcDumpManifestStaticEntry$1 } from "./index-vAX6bYuc.mjs";
+import { C as RpcFunctionType, S as RpcFunctionSetupResult, T as RpcReturnSchema, _ as RpcFunctionDefinition, i as RpcArgsSchema, v as RpcFunctionDefinitionAny, w as RpcFunctionsCollector } from "./types-Djq7CBXh.mjs";
 //#region src/rpc/cache.d.ts
 interface RpcCacheOptions {
   functions: string[];
@@ -54,7 +53,7 @@ declare function getRpcHandler<NAME extends string, TYPE extends RpcFunctionType
 //#endregion
 //#region src/rpc/serialization.d.ts
 /**
- * Wire format used by the WS RPC transport.
+ * Wire format used by the live RPC transports (WebSocket and SSE).
  *
  * - **JSON (default, unprefixed):** payload is plain JSON text. Used when
  *   the dispatched method is declared `jsonSerializable: true`. Encoded
@@ -133,32 +132,4 @@ declare function validateDefinitions(definitions: readonly RpcFunctionDefinition
  */
 declare function validateDefinition(definition: RpcFunctionDefinitionAny): void;
 //#endregion
-//#region src/rpc/index.d.ts
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-declare const collectStaticRpcDump: typeof collectStaticRpcDump$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-declare const createClientFromDump: typeof createClientFromDump$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-declare const dumpFunctions: typeof dumpFunctions$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-declare const getDefinitionsWithDumps: typeof getDefinitionsWithDumps$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-declare const reviveDumpError: typeof reviveDumpError$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-declare const serializeDumpError: typeof serializeDumpError$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-type StaticRpcDumpCollection = StaticRpcDumpCollection$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-type StaticRpcDumpFile = StaticRpcDumpFile$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-type StaticRpcDumpManifest = StaticRpcDumpManifest$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-type StaticRpcDumpManifestQueryEntry = StaticRpcDumpManifestQueryEntry$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-type StaticRpcDumpManifestStaticEntry = StaticRpcDumpManifestStaticEntry$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-type StaticRpcDumpManifestValue = StaticRpcDumpManifestValue$1;
-/** @deprecated Import from `devframe/rpc/dump` instead. */
-type StaticRpcDumpSerialization = StaticRpcDumpSerialization$1;
-//#endregion
-export { defineRpcFunction as C, RpcCacheOptions as E, createDefineWrapperWithContext as S, RpcCacheManager as T, validateRpcReturn as _, StaticRpcDumpManifestStaticEntry as a, getRpcHandler as b, collectStaticRpcDump as c, getDefinitionsWithDumps as d, reviveDumpError as f, validateRpcArgs as g, validateDefinitions as h, StaticRpcDumpManifestQueryEntry as i, createClientFromDump as l, validateDefinition as m, StaticRpcDumpFile as n, StaticRpcDumpManifestValue as o, serializeDumpError as p, StaticRpcDumpManifest as r, StaticRpcDumpSerialization as s, StaticRpcDumpCollection as t, dumpFunctions as u, STRUCTURED_CLONE_PREFIX as v, RpcFunctionsCollectorBase as w, getRpcResolvedSetupResult as x, strictJsonStringify as y };
+export { STRUCTURED_CLONE_PREFIX as a, getRpcResolvedSetupResult as c, RpcFunctionsCollectorBase as d, RpcCacheManager as f, validateRpcReturn as i, createDefineWrapperWithContext as l, validateDefinitions as n, strictJsonStringify as o, RpcCacheOptions as p, validateRpcArgs as r, getRpcHandler as s, validateDefinition as t, defineRpcFunction as u };

package/dist/index.d.mts

@@ -1,8 +1,15 @@
-import { $ as DevframeRpcServerFunctions, A as DevframeSettingsStore, At as DevframeAgentHostEvents, B as DevframeDefineDiagnosticsOptions, C as DevframeServicesHost, Ct as AgentResourceContent, D as DevframeScopedStreamingHost, Dt as AgentToolProvider, E as DevframeScopedNodeRpc, Et as AgentToolInput, F as ScopedSharedStates, G as RpcBroadcastOptions, H as DevframeDiagnosticsHost, I as SettingsForNamespace, J as RpcSharedStateHost, K as RpcFunctionsHost, L as DevframeViewHost, M as ScopedClientFunctions, Mt as EventUnsubscribe, N as ScopedRpcFn, Nt as EventsMap, O as DevframeSettings, Ot as AgentToolProviderHandle, P as ScopedServerFunctions, Q as DevframeRpcClientFunctions, R as DevframeHost, S as DevframeServiceOf, St as AgentResource, T as DevframeScopedNodeContext, Tt as AgentTool, U as DevframeDiagnosticsLogger, V as DevframeDiagnosticsDefinition, W as DevframeNodeRpcSession, X as RpcStreamingChannelOptions, Y as RpcStreamingChannel, Z as RpcStreamingHost, _ as ConnectionMeta, a as DevframeDockDefaults, b as DevframeNodeContext, bt as AgentHandle, c as DevframeSetupInfo, d as McpRouteOptions, et as DevframeRpcSharedStates, f as defineDevframe, g as Thenable, h as PartialWithoutId, i as DevframeDeploymentKind, j as ScopedBroadcastOptions, jt as EventEmitter, k as DevframeSettingsRegistry, kt as DevframeAgentHost, l as DevframeSpaOptions, m as EntriesToObject, n as DevframeCliOptions, o as DevframeDuplicationStrategy, q as RpcSharedStateGetOptions, r as DevframeDefinition, s as DevframeRuntime, t as DevframeBrowserContext, u as DevframeWsOptions, v as ConnectionMetaWebsocket, w as DevframeServicesRegistry, wt as AgentResourceInput, x as DevframeServiceId, xt as AgentManifest, y as DevframeCapabilities, z as DevframeStorageScope } from "./devframe-mQ4qZAuo.mjs";
-import { C as RpcFunctionType, T as RpcReturnSchema, _ as RpcFunctionDefinition, g as RpcFunctionAgentOptions, i as RpcArgsSchema } from "./types-CnJSgRVa.mjs";
-import "./index-Dbw1p5ch.mjs";
-import { n as DevframeNodeRpcSessionMeta } from "./ws-server-uKQcClcJ.mjs";
+import { A as ScopedServerFunctions, B as RpcFunctionsHost, C as DevframeScopedStreamingHost, Ct as DevframeAgentHost, D as ScopedBroadcastOptions, Dt as EventsMap, E as DevframeSettingsStore, Et as EventUnsubscribe, F as DevframeStorageScope, G as RpcStreamingHost, H as RpcSharedStateHost, I as DevframeDiagnosticsHost, J as DevframeRpcSharedStates, K as DevframeRpcClientFunctions, L as DevframeDiagnosticsLogger, M as SettingsForNamespace, N as DevframeViewHost, O as ScopedClientFunctions, P as DevframeHost, R as DevframeNodeRpcSession, S as DevframeScopedNodeRpc, St as AgentToolProviderHandle, T as DevframeSettingsRegistry, Tt as EventEmitter, U as RpcStreamingChannel, V as RpcSharedStateGetOptions, W as RpcStreamingChannelOptions, _ as DevframeServiceId, _t as AgentResourceContent, a as DevframeDuplicationStrategy, b as DevframeServicesRegistry, bt as AgentToolInput, c as DevframeWsOptions, d as ConnectionMeta, f as ConnectionMetaSse, g as DevframeNodeContext, gt as AgentResource, h as DevframeConnectionConfigsRegistry, ht as AgentManifest, i as DevframeDockDefaults, j as ScopedSharedStates, k as ScopedRpcFn, l as McpRouteOptions, m as DevframeCapabilities, mt as AgentHandle, n as DevframeDefinition, o as DevframeSetupInfo, p as ConnectionMetaWebsocket, q as DevframeRpcServerFunctions, r as DevframeDeploymentKind, s as DevframeSseOptions, t as DevframeCliOptions, v as DevframeServiceOf, vt as AgentResourceInput, w as DevframeSettings, wt as DevframeAgentHostEvents, x as DevframeScopedNodeContext, xt as AgentToolProvider, y as DevframeServicesHost, yt as AgentTool, z as RpcBroadcastOptions } from "./devframe-DJMg0WLe.mjs";
+import "./index-tdrk1bzV.mjs";
+import { C as RpcFunctionType, T as RpcReturnSchema, _ as RpcFunctionDefinition, g as RpcFunctionAgentOptions, i as RpcArgsSchema } from "./types-Djq7CBXh.mjs";
+import { d as DevframeRpcConnection, f as DevframeRpcConnectionRequest, p as DevframeRpcTransportKind, u as DevframeNodeRpcSessionMeta } from "./ws-server-D1d3QM9f.mjs";
+import { i as DevframeDefineDiagnosticsOptions } from "./nostics-SPGDgHEP.mjs";
+import { a as RemoteAssetsStore, i as RemoteAssetsProviderCustom, n as RemoteAssetsErrorMessage, o as StaticAssetsSource, r as RemoteAssetsProvider, t as RemoteAssets } from "./remote-assets-Bg4gCUZ_.mjs";
 //#region src/define.d.ts
 declare const defineRpcFunction: <NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeNodeContext>) => RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevframeNodeContext>;
+/**
+ * Identity helper that types a devframe definition — the primary authoring
+ * entry point. Import it from the package root: `import { defineDevframe } from 'devframe'`.
+ */
+declare function defineDevframe(d: DevframeDefinition): DevframeDefinition;
 //#endregion
-export { type AgentHandle, type AgentManifest, type AgentResource, type AgentResourceContent, type AgentResourceInput, type AgentTool, type AgentToolInput, type AgentToolProvider, type AgentToolProviderHandle, type ConnectionMeta, type ConnectionMetaWebsocket, type DevframeAgentHost, type DevframeAgentHostEvents, type DevframeBrowserContext, type DevframeCapabilities, type DevframeCliOptions, type DevframeDefineDiagnosticsOptions, type DevframeDefinition, type DevframeDeploymentKind, type DevframeDiagnosticsDefinition, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, type DevframeDockDefaults, type DevframeDuplicationStrategy, type DevframeHost, type DevframeNodeContext, type DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, type DevframeRpcClientFunctions, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, type DevframeRuntime, type DevframeScopedNodeContext, type DevframeScopedNodeRpc, type DevframeScopedStreamingHost, type DevframeServiceId, type DevframeServiceOf, type DevframeServicesHost, type DevframeServicesRegistry, type DevframeSettings, type DevframeSettingsRegistry, type DevframeSettingsStore, type DevframeSetupInfo, type DevframeSpaOptions, type DevframeStorageScope, type DevframeViewHost, type DevframeWsOptions, type EntriesToObject, type EventEmitter, type EventUnsubscribe, type EventsMap, type McpRouteOptions, type PartialWithoutId, type RpcBroadcastOptions, type RpcFunctionAgentOptions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost, type ScopedBroadcastOptions, type ScopedClientFunctions, type ScopedRpcFn, type ScopedServerFunctions, type ScopedSharedStates, type SettingsForNamespace, type Thenable, type defineDevframe, defineRpcFunction };
+export { type AgentHandle, type AgentManifest, type AgentResource, type AgentResourceContent, type AgentResourceInput, type AgentTool, type AgentToolInput, type AgentToolProvider, type AgentToolProviderHandle, type ConnectionMeta, type ConnectionMetaSse, type ConnectionMetaWebsocket, type DevframeAgentHost, type DevframeAgentHostEvents, type DevframeCapabilities, type DevframeCliOptions, type DevframeConnectionConfigsRegistry, type DevframeDefineDiagnosticsOptions, type DevframeDefinition, type DevframeDeploymentKind, type DevframeDiagnosticsHost, type DevframeDiagnosticsLogger, type DevframeDockDefaults, type DevframeDuplicationStrategy, type DevframeHost, type DevframeNodeContext, type DevframeNodeRpcSession, type DevframeNodeRpcSessionMeta, type DevframeRpcClientFunctions, type DevframeRpcConnection, type DevframeRpcConnectionRequest, type DevframeRpcServerFunctions, type DevframeRpcSharedStates, type DevframeRpcTransportKind, type DevframeScopedNodeContext, type DevframeScopedNodeRpc, type DevframeScopedStreamingHost, type DevframeServiceId, type DevframeServiceOf, type DevframeServicesHost, type DevframeServicesRegistry, type DevframeSettings, type DevframeSettingsRegistry, type DevframeSettingsStore, type DevframeSetupInfo, type DevframeSseOptions, type DevframeStorageScope, type DevframeViewHost, type DevframeWsOptions, type EventEmitter, type EventUnsubscribe, type EventsMap, type McpRouteOptions, type RemoteAssets, type RemoteAssetsErrorMessage, type RemoteAssetsProvider, type RemoteAssetsProviderCustom, type RemoteAssetsStore, type RpcBroadcastOptions, type RpcFunctionAgentOptions, type RpcFunctionsHost, type RpcSharedStateGetOptions, type RpcSharedStateHost, type RpcStreamingChannel, type RpcStreamingChannelOptions, type RpcStreamingHost, type ScopedBroadcastOptions, type ScopedClientFunctions, type ScopedRpcFn, type ScopedServerFunctions, type ScopedSharedStates, type SettingsForNamespace, type StaticAssetsSource, defineDevframe, defineRpcFunction };

package/dist/index.mjs

@@ -1,5 +1,12 @@
 import { t as createDefineWrapperWithContext } from "./define-BLWPsH6y.mjs";
 //#region src/define.ts
 const defineRpcFunction = createDefineWrapperWithContext();
+/**
+* Identity helper that types a devframe definition — the primary authoring
+* entry point. Import it from the package root: `import { defineDevframe } from 'devframe'`.
+*/
+function defineDevframe(d) {
+	return d;
+}
 //#endregion
-export { defineRpcFunction };
+export { defineDevframe, defineRpcFunction };

package/dist/{instance-registry-BnnA2Eoh.mjs → instance-registry-WvQkt42E.mjs}

@@ -1,9 +1,16 @@
-import { t as diagnostics } from "./diagnostics-D7wM2cwM.mjs";
+import { n as __exportAll } from "./rolldown-runtime-JspESFgx.mjs";
+import { t as diagnostics } from "./diagnostics-DOQPnQmX.mjs";
 import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "pathe";
 import process from "node:process";
 import { homedir } from "node:os";
 //#region src/node/instance-registry.ts
+var instance_registry_exports = /* @__PURE__ */ __exportAll({
+	listLiveDevframeInstances: () => listLiveDevframeInstances,
+	probeDevframeOrigin: () => probeDevframeOrigin,
+	readDevframeInstances: () => readDevframeInstances,
+	registerDevframeInstance: () => registerDevframeInstance
+});
 /** Environment variable overriding the registry directory (tests, CI). */
 const DEVFRAME_INSTANCES_DIR_ENV = "DEVFRAME_INSTANCES_DIR";
 /** Environment variable disabling instance registration entirely. */
@@ -35,8 +42,6 @@ function isRegistryDisabled() {
 * crash are pruned by readers whose liveness probe fails. Registration never
 * throws — a write failure degrades to a coded warning (`DF0045`), since a
 * dev server must not die over discovery metadata.
-*
-* @experimental
 */
 function registerDevframeInstance(record, options = {}) {
 	const dir = resolveInstancesDir(options.instancesDir);
@@ -71,8 +76,6 @@ function registerDevframeInstance(record, options = {}) {
 /**
 * Read every record in the registry directory, dropping unparseable files.
 * Liveness is the caller's concern — see {@link probeDevframeInstance}.
-*
-* @experimental
 */
 function readDevframeInstances(options = {}) {
 	const dir = resolveInstancesDir(options.instancesDir);
@@ -148,8 +151,6 @@ async function probeDevframeInstance(record, options = {}) {
 * records left behind by killed processes shadow the server currently bound
 * there: per `(port, basePath)` only the newest record survives, older
 * ghosts are pruned with the dead.
-*
-* @experimental
 */
 async function listLiveDevframeInstances(options = {}) {
 	const dir = resolveInstancesDir(options.instancesDir);
@@ -187,4 +188,4 @@ async function listLiveDevframeInstances(options = {}) {
 	};
 }
 //#endregion
-export { probeDevframeOrigin as n, registerDevframeInstance as r, listLiveDevframeInstances as t };
+export { registerDevframeInstance as i, listLiveDevframeInstances as n, probeDevframeOrigin as r, instance_registry_exports as t };

package/dist/instance-shell-CMFyszWJ.mjs

@@ -0,0 +1,486 @@
+import "./constants.mjs";
+import { t as diagnostics } from "./diagnostics-DOQPnQmX.mjs";
+import { t as getInternalContext } from "./context-xdynGSLP.mjs";
+import { createInteractiveAuth } from "./recipes/interactive-auth.mjs";
+import { createServer } from "node:http";
+import process from "node:process";
+import { isIP } from "node:net";
+import { joinURL, withLeadingSlash, withoutLeadingSlash, withoutTrailingSlash } from "ufo";
+import { H3, defineHandler, toNodeHandler } from "h3";
+//#region src/node/utils.ts
+const NON_DIALABLE_HOSTS = /* @__PURE__ */ new Set([
+	"0.0.0.0",
+	"127.0.0.1",
+	"::",
+	"0000:0000:0000:0000:0000:0000:0000:0000",
+	""
+]);
+/** Map a bind host to a host a client can actually connect to. */
+function toDialableHost(host) {
+	return NON_DIALABLE_HOSTS.has(host) ? "localhost" : host;
+}
+/** Format a bind host for use in a URL authority (dialable, IPv6-bracketed). */
+function formatHostForUrl(host) {
+	const dialable = toDialableHost(host);
+	return isIP(dialable) === 6 ? `[${dialable}]` : dialable;
+}
+function normalizeHttpServerUrl(host, port) {
+	return `http://${formatHostForUrl(host)}:${port}`;
+}
+//#endregion
+//#region src/node/instance-shell.ts
+/**
+* Compose an h3 + WebSocket RPC server for a devframe context — the low-level
+* "listen on a port (or share one) + attach the WS transport" binding the
+* side-car and shared-server tiers below are built on. Owns and listens on a
+* fresh `node:http` server unless `server` is supplied, in which case it only
+* attaches the upgrade listener and leaves that server's lifecycle to its
+* owner.
+*/
+async function bindHttpAndWs(options) {
+	const { context, port, core } = options;
+	const bindHost = options.host;
+	const app = new H3();
+	const ownsHttpServer = !options.server;
+	const httpServer = options.server ?? createServer(toNodeHandler(app));
+	const rpcHost = context.rpc;
+	const websocket = options.websocket !== false;
+	let ws;
+	let closeWs = async () => {};
+	if (websocket) {
+		const { attachWsRpcTransport } = await import("./rpc/transports/ws-server.mjs");
+		const transport = attachWsRpcTransport(core.rpcGroup, {
+			server: httpServer,
+			path: options.path,
+			destroyUnmatched: options.destroyUnmatched ?? ownsHttpServer,
+			allowedOrigins: options.allowedOrigins,
+			onConnected: core.onConnected,
+			onDisconnected: core.onDisconnected
+		});
+		ws = transport.ws;
+		closeWs = transport.close;
+	}
+	if (ownsHttpServer) try {
+		await new Promise((resolve, reject) => {
+			const onError = (error) => reject(error);
+			httpServer.once("error", onError);
+			httpServer.listen(port, bindHost, () => {
+				httpServer.removeListener("error", onError);
+				resolve();
+			});
+		});
+	} catch (error) {
+		await closeWs().catch(() => {});
+		throw diagnostics.DF0052({
+			host: bindHost,
+			port,
+			reason: error instanceof Error ? error.message : String(error),
+			cause: error
+		});
+	}
+	const address = httpServer.address();
+	const resolvedPort = typeof address === "object" && address ? address.port : port;
+	const origin = normalizeHttpServerUrl(bindHost, resolvedPort);
+	const internal = getInternalContext(context);
+	const wsUrl = `ws://${formatHostForUrl(bindHost)}:${resolvedPort}${options.path ?? ""}`;
+	if (websocket) internal.setWsEndpoint({ url: wsUrl });
+	function connectionMeta() {
+		const jsonSerializableMethods = [];
+		for (const def of rpcHost.definitions.values()) if (def.jsonSerializable === true) jsonSerializableMethods.push(def.name);
+		return {
+			backend: "websocket",
+			websocket: { path: options.path },
+			jsonSerializableMethods
+		};
+	}
+	return {
+		origin,
+		port: resolvedPort,
+		app,
+		ws,
+		rpcGroup: core.rpcGroup,
+		connectionMeta,
+		async close() {
+			await closeWs();
+			if (ownsHttpServer) await new Promise((r) => httpServer.close(() => r()));
+			if (websocket && getInternalContext(context).wsEndpoint?.url === wsUrl) getInternalContext(context).setWsEndpoint(void 0);
+		}
+	};
+}
+/**
+* Translate the public `register?: boolean | Partial<DevframeInstanceRecord>`
+* option into a shell {@link InstanceRegisterConfig}, or `undefined` when
+* registration is opted out. The object form supplies record overrides on top
+* of the caller-provided identity defaults.
+*/
+function resolveInstanceRegister(option, defaults) {
+	if (!option) return void 0;
+	return {
+		id: defaults.id,
+		...defaults.name !== void 0 ? { name: defaults.name } : {},
+		...defaults.rootDir !== void 0 ? { rootDir: defaults.rootDir } : {},
+		...typeof option === "object" ? { overrides: option } : {}
+	};
+}
+/** Compare two URL paths ignoring a trailing slash. */
+function samePath(a, b) {
+	return withoutTrailingSlash(a) === withoutTrailingSlash(b);
+}
+/**
+* Copy a web `Response` from a fetch-style transport handler onto the h3
+* event's response and return its body — mirroring the MCP route's bridge.
+* Returning the body (a `ReadableStream`, or `''` for an empty one — h3
+* middleware only falls through on `undefined`) terminates the chain with
+* the status/headers set here instead of continuing to the SPA catch-all.
+*/
+function respondWith(event, response) {
+	event.res.status = response.status;
+	event.res.statusText = response.statusText;
+	response.headers.forEach((value, key) => {
+		event.res.headers.set(key, value);
+	});
+	return response.body ?? "";
+}
+/**
+* The shared machinery behind `initDevframe` and `initHub`: one mount base,
+* one h3 app, one lazily-derived public origin (and the auth banner that waits
+* for it), one WebSocket binding, and the fetch / connect-middleware pair that
+* serves them. Each factory supplies only what makes it itself — its context,
+* its routes, its diagnostics — through `init` / `mount`.
+*
+* Nothing here listens on a port unless a side-car was explicitly requested:
+* the default tier leaves the socket `unbound`, so a host chains it onto its
+* own server through {@link InstanceShell.attach} /
+* {@link InstanceShell.handleUpgrade}.
+*
+* @internal
+*/
+function createInstanceShell(options) {
+	const base = options.base;
+	const baseNoSlash = withoutTrailingSlash(base);
+	const app = options.app ?? new H3();
+	const wsDisabled = options.ws === false;
+	const ws = options.ws === false ? {} : options.ws ?? {};
+	const route = withoutLeadingSlash(ws.route ?? "__ws");
+	/** Where an upgrade lands on the host's own origin. */
+	const routePath = joinURL(base, route);
+	/** What `__connection.json` advertises for a same-origin socket. */
+	const advertisedPath = options.absoluteWsPath ? routePath : route;
+	const sidecarRequested = ws.port != null || ws.sidecar === true;
+	const tier = wsDisabled ? "disabled" : sidecarRequested ? "sidecar" : options.server ? "server" : ws.url ? "external" : "unbound";
+	const sseEnabled = options.sse !== false && tier !== "external";
+	const sseRoute = withoutLeadingSlash((typeof options.sse === "object" ? options.sse.route : void 0) ?? "__sse");
+	const sseRoutePath = joinURL(base, sseRoute);
+	const advertisedSsePath = options.absoluteWsPath ? sseRoutePath : sseRoute;
+	let derivedOrigin;
+	function currentOrigin() {
+		return (typeof options.origin === "function" ? options.origin() : options.origin) || derivedOrigin;
+	}
+	let authHandler;
+	let bannerPrinted = false;
+	function maybePrintBanner() {
+		if (bannerPrinted || !authHandler || !currentOrigin()) return;
+		bannerPrinted = true;
+		authHandler.printBanner();
+	}
+	let meta;
+	let registration;
+	let registerPromise;
+	/**
+	* Publish the instance in the global registry the moment both its origin
+	* and connection meta are known — at init end for a pinned origin, or on
+	* the first request for a derived one. Registration never throws (the
+	* registry writer degrades to a coded warning), so failures never surface.
+	*/
+	function maybeRegister() {
+		const cfg = options.register;
+		const origin = currentOrigin();
+		if (!cfg || registerPromise || !origin || !meta) return;
+		const resolvedMeta = meta;
+		registerPromise = import("./instance-registry-WvQkt42E.mjs").then((n) => n.t).then(({ registerDevframeInstance }) => {
+			let port = 0;
+			try {
+				const url = new URL(origin);
+				port = Number(url.port) || (url.protocol === "https:" ? 443 : 80);
+			} catch {}
+			registration = registerDevframeInstance({
+				pid: process.pid,
+				port,
+				origin,
+				basePath: base,
+				id: cfg.id,
+				...cfg.name !== void 0 ? { name: cfg.name } : {},
+				rootDir: cfg.rootDir ?? process.cwd(),
+				mcp: resolvedMeta.mcp ? { path: joinURL(base, resolvedMeta.mcp.path) } : null,
+				startedAt: Date.now(),
+				...cfg.overrides
+			});
+		}).catch(() => {});
+	}
+	function noteOrigin(origin) {
+		derivedOrigin ??= origin;
+		maybePrintBanner();
+		maybeRegister();
+	}
+	let started;
+	let transport;
+	let dispose;
+	let ctx;
+	const api = {
+		base,
+		app,
+		origin: currentOrigin,
+		connectionMeta: () => meta
+	};
+	/**
+	* Auth resolution: gate by default, `false` opts out, a handler object
+	* installs a custom scheme. The `external` tier has no local transport to
+	* gate — the server behind `ws.url` owns auth — so it resolves to nothing.
+	*/
+	function resolveAuth() {
+		if (options.auth === false) return false;
+		if (typeof options.auth === "object") {
+			authHandler = options.auth;
+			return options.auth;
+		}
+		authHandler = createInteractiveAuth(ctx);
+		return authHandler;
+	}
+	/**
+	* The context's RPC core (birpc group, session lifecycle, auth gate) —
+	* one per instance, shared by every transport binding (WS and SSE), so a
+	* WS peer and an SSE session live in the same session/broadcast space.
+	* Built lazily: an `unbound` host that never wires a transport pays
+	* nothing for it, not even the imports. `resolvedAuth` and `ctx` are
+	* assigned during `init()` before any caller can reach this.
+	*/
+	let resolvedAuth = false;
+	let corePromise;
+	function ensureCore() {
+		corePromise ??= import("./rpc-core-DMTe-hLo.mjs").then((n) => n.n).then(({ createContextRpcServer }) => createContextRpcServer({
+			context: ctx,
+			auth: resolvedAuth,
+			onPeerConnect: options.onPeerConnect,
+			onPeerDisconnect: options.onPeerDisconnect
+		}));
+		return corePromise;
+	}
+	/**
+	* The SSE transport, built on the first request to its route so an
+	* instance nobody dials over SSE never loads it.
+	*/
+	let ssePromise;
+	function ensureSse() {
+		ssePromise ??= (async () => {
+			const [core, { attachSseRpcTransport }] = await Promise.all([ensureCore(), import("./rpc/transports/sse-server.mjs")]);
+			return attachSseRpcTransport(core.rpcGroup, {
+				allowedOrigins: options.allowedOrigins,
+				onConnected: core.onConnected,
+				onDisconnected: core.onDisconnected
+			});
+		})();
+		return ssePromise;
+	}
+	/**
+	* A side-car server on its own port. `getPort` probes and the bind can
+	* still race (or disagree across the v4/v6 duals of `localhost`), so an
+	* auto-port side-car retries on a fresh random port instead of failing
+	* init; a pinned `ws.port` is honored as given and fails loudly.
+	*/
+	async function startSidecar(core) {
+		const sidecarHost = options.host ?? "localhost";
+		const start = (port) => bindHttpAndWs({
+			context: ctx,
+			core,
+			host: sidecarHost,
+			port,
+			path: withLeadingSlash(route),
+			allowedOrigins: options.allowedOrigins
+		});
+		if (ws.port != null) return await start(ws.port);
+		const { getPort } = await import("./dist-eNI9qM_I.mjs").then((n) => n.t);
+		let lastError;
+		for (let attempt = 0; attempt < 3; attempt++) {
+			const port = attempt === 0 && options.resolveSidecarPort ? await options.resolveSidecarPort(sidecarHost) : await getPort({
+				random: true,
+				host: sidecarHost
+			});
+			try {
+				return await start(port);
+			} catch (error) {
+				lastError = error;
+			}
+		}
+		throw lastError;
+	}
+	async function init() {
+		const result = await options.init(api);
+		ctx = result.context;
+		dispose = result.dispose;
+		resolvedAuth = tier === "external" ? false : resolveAuth();
+		let websocketMeta;
+		if (tier === "sidecar") {
+			started = await startSidecar(await ensureCore());
+			websocketMeta = {
+				port: started.port,
+				path: route
+			};
+		} else if (tier === "server") {
+			started = await bindHttpAndWs({
+				context: ctx,
+				core: await ensureCore(),
+				host: options.host ?? "localhost",
+				port: 0,
+				server: options.server,
+				path: routePath,
+				allowedOrigins: options.allowedOrigins,
+				destroyUnmatched: options.destroyUnmatchedUpgrades
+			});
+			websocketMeta = { path: advertisedPath };
+		} else if (tier === "external") websocketMeta = ws.url;
+		else if (tier === "unbound") websocketMeta = { path: advertisedPath };
+		if (!wsDisabled && ws.url) websocketMeta = ws.url;
+		if (sseEnabled) app.use(sseRoutePath, defineHandler(async (event) => respondWith(event, await (await ensureSse()).handler(event.req))));
+		meta = {
+			backend: wsDisabled ? sseEnabled ? "sse" : "none" : "websocket",
+			...websocketMeta !== void 0 ? { websocket: websocketMeta } : {},
+			...sseEnabled ? { sse: { path: advertisedSsePath } } : {},
+			...result.mcp ? { mcp: result.mcp } : {}
+		};
+		if (Object.keys(ctx.staticConfig).length > 0) meta.configs = ctx.staticConfig;
+		await options.mount?.(ctx, meta, api);
+		maybePrintBanner();
+		maybeRegister();
+	}
+	const initPromise = init();
+	initPromise.catch(() => {});
+	const contextPromise = initPromise.then(() => ctx);
+	contextPromise.catch(() => {});
+	/**
+	* The `unbound` tier: the RPC core and its crossws adapter, bound to
+	* nothing. Built on the first `attach` / `handleUpgrade` — a host that
+	* never wires the socket (or whose runtime brings its own WS transport)
+	* pays nothing for it, not even the adapter's imports.
+	*/
+	let transportPromise;
+	function ensureTransport() {
+		transportPromise ??= initPromise.then(async () => {
+			const [core, { attachWsRpcTransport }] = await Promise.all([ensureCore(), import("./rpc/transports/ws-server.mjs")]);
+			transport = attachWsRpcTransport(core.rpcGroup, {
+				unbound: true,
+				path: routePath,
+				allowedOrigins: options.allowedOrigins,
+				onConnected: core.onConnected,
+				onDisconnected: core.onDisconnected
+			});
+			return transport;
+		});
+		return transportPromise;
+	}
+	async function handleRequest(request) {
+		await initPromise;
+		noteOrigin(new URL(request.url).origin);
+		const response = await app.fetch(request);
+		if (response.status === 404) return new Response(null, { status: 404 });
+		return response;
+	}
+	let nodeHandler;
+	function nodeMiddleware(req, res, next) {
+		let pathname = req.url ?? "/";
+		try {
+			pathname = new URL(pathname, "http://localhost").pathname;
+		} catch {}
+		if (!(samePath(pathname, baseNoSlash) || pathname.startsWith(base))) {
+			if (next) {
+				next();
+				return;
+			}
+			res.statusCode = 404;
+			res.end();
+			return;
+		}
+		initPromise.then(async () => {
+			const host = req.headers.host;
+			if (host) {
+				const encrypted = req.socket.encrypted;
+				noteOrigin(`${encrypted ? "https" : "http"}://${host}`);
+			}
+			if (!nodeHandler) {
+				const { toNodeHandler } = await import("h3/node");
+				nodeHandler = toNodeHandler(app);
+			}
+			return nodeHandler(req, res);
+		}).catch((err) => {
+			if (next) {
+				next(err);
+				return;
+			}
+			res.statusCode = 500;
+			res.end();
+		});
+	}
+	/** The `unbound` tier is the only one whose socket the host may drive. */
+	function assertUnbound() {
+		if (tier === "disabled") throw diagnostics.DF0057();
+		if (tier === "external") throw diagnostics.DF0056({ url: ws.url });
+		if (tier !== "unbound") throw diagnostics.DF0055({ tier });
+	}
+	/**
+	* Publish the socket's absolute URL on the context, so surfaces that hand
+	* out a complete endpoint (the hub's remote docks) work on this tier too.
+	* {@link bindHttpAndWs} does the same for the tiers it owns.
+	*/
+	function publishWsEndpoint(server) {
+		const record = () => {
+			const address = server.address();
+			if (typeof address !== "object" || !address) return;
+			const host = options.host ?? (address.address === "::" || address.address === "0.0.0.0" ? "localhost" : address.address);
+			getInternalContext(ctx).setWsEndpoint({ url: `ws://${formatHostForUrl(host)}:${address.port}${routePath}` });
+		};
+		if (server.listening) record();
+		else server.once("listening", record);
+	}
+	function handleUpgrade(req, socket, head) {
+		assertUnbound();
+		if (transport) {
+			transport.handleUpgrade(req, socket, head);
+			return;
+		}
+		ensureTransport().then((live) => live.handleUpgrade(req, socket, head)).catch(() => socket.destroy());
+	}
+	function attach(server) {
+		assertUnbound();
+		server.on("upgrade", handleUpgrade);
+		ensureTransport().then(() => publishWsEndpoint(server)).catch(() => {});
+		return () => server.off("upgrade", handleUpgrade);
+	}
+	return {
+		base,
+		handler: handleRequest,
+		nodeMiddleware,
+		ready: initPromise,
+		context: contextPromise,
+		connectionMeta: () => meta ?? options.onMetaUnavailable(),
+		handleUpgrade,
+		attach,
+		async close() {
+			await initPromise.catch(() => {});
+			await registerPromise?.catch(() => {});
+			registration?.unregister();
+			await dispose?.();
+			await ssePromise?.then((live) => live.close()).catch(() => {});
+			await started?.close();
+			await transportPromise?.then((live) => live.close()).catch(() => {});
+		},
+		internals: {
+			get started() {
+				return started;
+			},
+			get authHandler() {
+				return authHandler;
+			}
+		}
+	};
+}
+//#endregion
+export { normalizeHttpServerUrl as i, resolveInstanceRegister as n, samePath as r, createInstanceShell as t };