devframe 0.9.8 → 0.9.10

package/dist/constants.mjs

@@ -1,5 +1,6 @@
-import { t as DEVFRAME_EVENTS } from "./events-4daw0uK9.mjs";
+import { t as DEVFRAME_EVENTS } from "./events-BV4Dj59a.mjs";
 //#region src/constants.ts
+/** Devframe runtime routes and static output conventions. */
 const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 /**
 * Global key holding the serializable connection prepared by
@@ -10,7 +11,7 @@ const DEVFRAME_CONNECTION_KEY = "__DEVFRAME_CONNECTION__";
 /**
 * Route the WebSocket RPC endpoint is bound to, relative to a devframe's
 * base path. Sits next to `__connection.json` so the deployed SPA can reach
-* it on the same origin it loaded from — the dev server shares one port for
+* it on the same origin it loaded from: the dev server shares one port for
 * 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).
 */
@@ -20,7 +21,7 @@ const DEVFRAME_WS_ROUTE = "__ws";
 * 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
+* loaded from; the transport for hosts and proxies where the WebSocket
 * upgrade isn't available.
 */
 const DEVFRAME_SSE_ROUTE = "__sse";
@@ -34,7 +35,7 @@ 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
-* so an MCP client reaches it on the same origin the SPA loaded from — the
+* so an MCP client reaches it on the same origin the SPA loaded from; the
 * dev server shares one port for HTTP, WS, and MCP. Opt-in via `cli.mcp`.
 */
 const DEVFRAME_MCP_ROUTE = "__mcp";
@@ -79,7 +80,7 @@ const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin_token";
 /**
 * `postMessage` type the remote-assets fallback page posts to `window.parent`
 * on load. That page is what a devframe serves (with a 502) when its client
-* assets can be reached neither locally nor through their CDN provider — the
+* assets can be reached neither locally nor through their CDN provider; the
 * message lets an embedding viewer replace the bare page with its own UI
 * (`@devframes/hub-ui` does, in its iframe view). Payload shape:
 * `RemoteAssetsErrorMessage` (`devframe/types`).
@@ -87,7 +88,7 @@ const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin_token";
 const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE = DEVFRAME_EVENTS.postMessage.remoteAssetsError;
 /**
 * Prefix that marks an RPC method as callable before a connection is
-* trusted. This is the *only* rule the pre-trust gate applies — there is no
+* trusted. This is the *only* rule the pre-trust gate applies; there is no
 * per-method allowlist. Any handshake method a host adapter needs to reach
 * before authentication must be named `anonymous:<rest>` (e.g.
 * `anonymous:devframe:auth`).

package/dist/{context-omlma_1n.mjs → context-B29Oh0oA.mjs}

@@ -1,22 +1,27 @@
-import { i as defineDiagnostics } from "./nostics-CzECRXpE.mjs";
-import { t as diagnostics } from "./diagnostics-CD8nlgll.mjs";
+import { i as defineDiagnostics } from "./nostics-D0PvLZsn.mjs";
+import { r as diagnostics } from "./serialization-DFg5sUt6.mjs";
 import { RpcFunctionsCollectorBase } from "./rpc/index.mjs";
 import { defineRpcFunction } from "./index.mjs";
-import { t as DEVFRAME_EVENTS } from "./events-4daw0uK9.mjs";
+import { t as DEVFRAME_EVENTS } from "./events-BV4Dj59a.mjs";
 import { DEVFRAME_SERVICES_STATE_KEY } from "./constants.mjs";
-import { t as diagnostics$1 } from "./diagnostics-BXWW3VK-.mjs";
-import { a as DevframeAgentHost, i as satisfiesVersionRange, n as expandResolveFrom, r as importServicePackage, s as createEventEmitter, t as deepMergeOptionSets } from "./services-install-CqqQVls5.mjs";
-import { n as createDebug, t as resolveStaticAssetsSource } from "./remote-assets-DezQmPQU.mjs";
-import { t as createStorage } from "./storage-BXNVhKyR.mjs";
+import { t as diagnostics$1 } from "./diagnostics-DZA6KQ_Z.mjs";
+import { r as createEventEmitter, t as DevframeAgentHost } from "./host-agent-CKqSTEX9.mjs";
+import { n as createDebug, t as resolveStaticAssetsSource } from "./remote-assets-DMFzLSoH.mjs";
+import { i as satisfiesVersionRange, n as expandResolveFrom, r as importServicePackage, t as deepMergeOptionSets } from "./services-install-Ben4yh52.mjs";
+import { t as createStorage } from "./storage-B70AXK64.mjs";
+import { join } from "pathe";
 import { createSharedState } from "devframe/utils/shared-state";
 import process from "node:process";
-import { join } from "pathe";
 import { existsSync } from "node:fs";
 //#region src/node/host-diagnostics.ts
 var DevframeDiagnosticsHost = class {
 	context;
 	_registry = {};
 	logger = new Proxy({}, { get: (_, code) => this._registry[code] });
+	/**
+	* Already pre-wires devframe's ANSI console reporter, so no extra merging
+	* needed here, the host's `defineDiagnostics` just is the shared one.
+	*/
 	defineDiagnostics = defineDiagnostics;
 	constructor(context, initialDefinitions = []) {
 		this.context = context;
@@ -123,7 +128,16 @@ function createRpcSharedStateServerHost(rpc) {
 			if (!sharedState.has(key)) return void 0;
 			return (await host.get(key)).value();
 		},
-		dump: () => ({ inputs: host.keys().map((key) => [key]) })
+		/**
+		* Pre-compute snapshots for the build-mode static dump so the SPA
+		* can read them without a live server. The `undefined` fallback makes
+		* a key the build never created resolve like the live handler does
+		* (returning `undefined`) instead of failing the dump lookup.
+		*/
+		dump: () => ({
+			inputs: host.keys().map((key) => [key]),
+			fallback: void 0
+		})
 	});
 	rpc.register({
 		name: "devframe:rpc:server-state:set",
@@ -158,7 +172,7 @@ var StreamClosedError = class extends Error {
 	name = "StreamClosedError";
 };
 /**
-* Build a server-side stream sink. RPC-agnostic — the RPC host wires
+* Build a server-side stream sink. RPC-agnostic; the RPC host wires
 * `events.on('chunk' | 'end')` to broadcast, and reads `buffer` to replay
 * for late or reconnecting subscribers.
 */
@@ -229,7 +243,7 @@ function createStreamSink(options = {}) {
 	};
 }
 /**
-* Build a client-side stream reader. RPC-agnostic — the RPC host calls
+* Build a client-side stream reader. RPC-agnostic; the RPC host calls
 * `_push(seq, chunk)` on each incoming chunk and `_end(error?)` on the
 * terminal frame. Consumers iterate with `for await` or pipe `readable`.
 */
@@ -412,7 +426,7 @@ function streamKey(channel, id) {
 }
 /**
 * Build the server-side streaming host. Mirrors the layout of
-* `createRpcSharedStateServerHost` — registers a fixed set of internal
+* `createRpcSharedStateServerHost`: registers a fixed set of internal
 * RPC methods (`subscribe` / `unsubscribe` / `cancel`) once, then per-channel
 * state lives in a `Map<channelName, ChannelState>`.
 */
@@ -573,6 +587,10 @@ function createRpcStreamingServerHost(rpc) {
 			name,
 			options: {
 				replayWindow,
+				/**
+				* Default to a 30-second hold when replay is enabled so late
+				* subscribers can join after the producer finishes.
+				*/
 				closedStreamRetention: opts.closedStreamRetention ?? (replayWindow > 0 ? 3e4 : 0)
 			},
 			streams: /* @__PURE__ */ new Map(),
@@ -669,37 +687,39 @@ function createRpcStreamingServerHost(rpc) {
 			id: key.slice(sepIdx + 1)
 		};
 	}
+	function dropOutboundSubscriptions(meta) {
+		if (!meta.subscribedStreams) return;
+		for (const key of meta.subscribedStreams) {
+			const parsed = parseKey(key);
+			const state = parsed && channels.get(parsed.channelName);
+			const record = state && parsed && state.streams.get(parsed.id);
+			if (!parsed || !state || !record) continue;
+			record.subscribers.delete(meta);
+			if (record.subscribers.size === 0 && !record.sink.closed) record.sink.abort("all subscribers disconnected");
+			maybeFreeStream(state, parsed.id);
+		}
+		meta.subscribedStreams.clear();
+	}
+	function endInboundUploads(meta) {
+		if (!meta.uploadingStreams) return;
+		for (const key of meta.uploadingStreams) {
+			const parsed = parseKey(key);
+			const state = parsed && channels.get(parsed.channelName);
+			const record = state && parsed && state.inbound.get(parsed.id);
+			if (!parsed || !state || !record) continue;
+			record.reader._end({
+				name: "UploadDisconnected",
+				message: "Uploader disconnected before completing the stream"
+			});
+			state.inbound.delete(parsed.id);
+		}
+		meta.uploadingStreams.clear();
+	}
 	return {
 		create: createChannel,
 		_onSessionDisconnected(meta) {
-			if (meta.subscribedStreams) {
-				for (const key of meta.subscribedStreams) {
-					const parsed = parseKey(key);
-					if (!parsed) continue;
-					const state = channels.get(parsed.channelName);
-					const record = state?.streams.get(parsed.id);
-					if (!state || !record) continue;
-					record.subscribers.delete(meta);
-					if (record.subscribers.size === 0 && !record.sink.closed) record.sink.abort("all subscribers disconnected");
-					maybeFreeStream(state, parsed.id);
-				}
-				meta.subscribedStreams.clear();
-			}
-			if (meta.uploadingStreams) {
-				for (const key of meta.uploadingStreams) {
-					const parsed = parseKey(key);
-					if (!parsed) continue;
-					const state = channels.get(parsed.channelName);
-					const record = state?.inbound.get(parsed.id);
-					if (!state || !record) continue;
-					record.reader._end({
-						name: "UploadDisconnected",
-						message: "Uploader disconnected before completing the stream"
-					});
-					state.inbound.delete(parsed.id);
-				}
-				meta.uploadingStreams.clear();
-			}
+			dropOutboundSubscriptions(meta);
+			endInboundUploads(meta);
 		}
 	};
 }
@@ -763,6 +783,17 @@ var RpcFunctionsHostImpl = class extends RpcFunctionsCollectorBase {
 //#endregion
 //#region src/node/host-services.ts
 const debug = createDebug("devframe:services");
+/**
+* Per-RPC-host registry of the services already installed against it, keyed
+* by the RPC host object. A single wire service can be declared from more
+* than one devframe context that shares one RPC host (e.g. a kit that mounts
+* a definition alongside another context, so both iterate `def.services`).
+* The per-instance `installed` guard can't see across those sibling hosts, so
+* the second context would re-run the service factory and re-register its RPC,
+* hitting DF0021. Sharing the registry by RPC host makes the first install win
+* across every context on that host.
+*/
+const installedByRpcHost = /* @__PURE__ */ new WeakMap();
 function isServiceDefinition(input) {
 	return typeof input.setup === "function";
 }
@@ -784,13 +815,24 @@ function validateServiceDefinition(def) {
 	});
 }
 /**
+* Merge every installer's option set in declaration order (the default
+* deep-merge unions arrays and lets later scalars win; a service may override
+* with its own `mergeOptions`).
+*/
+function mergeInstallerOptions(def, entries) {
+	const sets = entries.map((entry) => entry.input.options).filter((options) => options !== void 0);
+	if (def.mergeOptions) return def.mergeOptions(sets);
+	return sets.length > 0 ? deepMergeOptionSets(sets) : void 0;
+}
+/**
 * Cross-plugin service registry (see `types/services.ts` for the contract).
 * Values are held per context instance; `whenAvailable` subscriptions make
-* the mechanism robust against setup ordering between provider and consumer.
+* the mechanism work regardless of setup ordering between provider and
+* consumer.
 *
 * On top of the in-process `provide`/`get` tier, this host implements the
 * **wire-service** lifecycle: `install()` queues definitions/descriptors,
-* `ready()` fires the collect-then-setup barrier — importing descriptor
+* `ready()` fires the collect-then-setup barrier: importing descriptor
 * packages, merging option sets per service, constructing each service once,
 * providing its node API under the package name, and advertising it to
 * clients through the `devframe:services` shared state.
@@ -800,11 +842,27 @@ var DevframeServicesHostImpl = class {
 	services = /* @__PURE__ */ new Map();
 	listeners = /* @__PURE__ */ new Map();
 	pending = /* @__PURE__ */ new Map();
-	installed = /* @__PURE__ */ new Map();
+	localInstalled = /* @__PURE__ */ new Map();
 	readyPromise;
 	constructor(context) {
 		this.context = context;
 	}
+	/**
+	* The install-dedup registry, shared across every services host that shares
+	* this host's RPC host so the first install of a package wins across sibling
+	* contexts. Falls back to a per-instance map when there is no RPC host (a
+	* context-less host only exercises the in-process `provide`/`get` tier).
+	*/
+	get installed() {
+		const rpc = this.context?.rpc;
+		if (!rpc) return this.localInstalled;
+		let registry = installedByRpcHost.get(rpc);
+		if (!registry) {
+			registry = /* @__PURE__ */ new Map();
+			installedByRpcHost.set(rpc, registry);
+		}
+		return registry;
+	}
 	provide(id, service) {
 		const key = id;
 		if (this.services.has(key)) throw diagnostics$1.DF0037({ id: key });
@@ -882,47 +940,75 @@ var DevframeServicesHostImpl = class {
 	}
 	async installPackage(pkg, entries) {
 		if (this.installed.has(pkg)) {
-			diagnostics$1.DF0066({ package: pkg });
-			return this.installed.get(pkg);
+			const api = this.installed.get(pkg);
+			if (this.services.has(pkg)) diagnostics$1.DF0066({ package: pkg });
+			else this.provide(pkg, api);
+			return api;
 		}
 		let def = entries.filter((entry) => isServiceDefinition(entry.input))[0]?.input;
 		if (!def) {
-			const required = entries.map((entry) => entry.input).some((descriptor) => descriptor.required === true);
-			const cwd = this.context?.cwd ?? process.cwd();
-			const resolveFroms = [
-				...entries.map((entry) => entry.resolveFrom && expandResolveFrom(entry.resolveFrom, cwd)),
-				this.context?.workspaceRoot,
-				cwd
-			];
-			let mod;
-			try {
-				mod = await importServicePackage(pkg, resolveFroms);
-			} catch (error) {
-				const reason = error instanceof Error ? error.message : String(error);
-				if (required) throw diagnostics$1.DF0067({
-					package: pkg,
-					reason,
-					cause: error
-				});
-				debug("optional service %s not importable, skipping: %s", pkg, reason);
-				return;
-			}
-			const factory = mod.default;
-			if (typeof factory !== "function") throw diagnostics$1.DF0070({
-				package: pkg,
-				reason: "its default export is not a factory function"
-			});
-			def = await factory();
-			if (!def || typeof def.setup !== "function") throw diagnostics$1.DF0070({
+			def = await this.importServiceDefinition(pkg, entries);
+			if (!def) return void 0;
+		}
+		this.checkVersionRanges(pkg, def, entries);
+		const options = mergeInstallerOptions(def, entries);
+		if (!this.context) throw diagnostics$1.DF0070({
+			package: pkg,
+			reason: "this services host has no node context to install into"
+		});
+		debug("installing service %s@%s (scope %s)", def.package, def.version, def.scope);
+		const scoped = this.context.scope(def.scope);
+		const api = await def.setup(scoped, options === void 0 ? {} : { options });
+		this.installed.set(pkg, api);
+		this.provide(def.package, api);
+		await this.advertise(def);
+		return api;
+	}
+	/**
+	* Import a descriptor-only package, run its factory, and validate the
+	* resulting definition. Returns `undefined` when an optional package can't
+	* be imported (the install is skipped); throws for a required one.
+	*/
+	async importServiceDefinition(pkg, entries) {
+		const required = entries.map((entry) => entry.input).some((descriptor) => descriptor.required === true);
+		const cwd = this.context?.cwd ?? process.cwd();
+		const resolveFroms = [
+			...entries.map((entry) => entry.resolveFrom && expandResolveFrom(entry.resolveFrom, cwd)),
+			this.context?.workspaceRoot,
+			cwd
+		];
+		let mod;
+		try {
+			mod = await importServicePackage(pkg, resolveFroms);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			if (required) throw diagnostics$1.DF0067({
 				package: pkg,
-				reason: "its factory did not return a definition with a `setup` function"
+				reason,
+				cause: error
 			});
-			if (typeof def.package !== "string" || def.package.length === 0) def = {
-				...def,
-				package: pkg
-			};
-			validateServiceDefinition(def);
+			debug("optional service %s not importable, skipping: %s", pkg, reason);
+			return;
 		}
+		const factory = mod.default;
+		if (typeof factory !== "function") throw diagnostics$1.DF0070({
+			package: pkg,
+			reason: "its default export is not a factory function"
+		});
+		let def = await factory();
+		if (!def || typeof def.setup !== "function") throw diagnostics$1.DF0070({
+			package: pkg,
+			reason: "its factory did not return a definition with a `setup` function"
+		});
+		if (typeof def.package !== "string" || def.package.length === 0) def = {
+			...def,
+			package: pkg
+		};
+		validateServiceDefinition(def);
+		return def;
+	}
+	/** Version-range checks against the resolved definition's real version. */
+	checkVersionRanges(pkg, def, entries) {
 		for (const entry of entries) {
 			const descriptor = entry.input;
 			if (isServiceDefinition(entry.input) || typeof descriptor.version !== "string") continue;
@@ -938,19 +1024,6 @@ var DevframeServicesHostImpl = class {
 				installed: def.version
 			});
 		}
-		const sets = entries.map((entry) => entry.input.options).filter((options) => options !== void 0);
-		const options = def.mergeOptions ? def.mergeOptions(sets) : sets.length > 0 ? deepMergeOptionSets(sets) : void 0;
-		if (!this.context) throw diagnostics$1.DF0070({
-			package: pkg,
-			reason: "this services host has no node context to install into"
-		});
-		debug("installing service %s@%s (scope %s)", def.package, def.version, def.scope);
-		const scoped = this.context.scope(def.scope);
-		const api = await def.setup(scoped, options === void 0 ? {} : { options });
-		this.installed.set(def.package, api);
-		this.provide(def.package, api);
-		await this.advertise(def);
-		return api;
 	}
 	advertisementState() {
 		return this.context.rpc.sharedState.get(DEVFRAME_SERVICES_STATE_KEY, { initialValue: {} });
@@ -1019,7 +1092,7 @@ const agentListResources = defineRpcFunction({
 /**
 * Built-in agent introspection RPC functions. Registered automatically
 * by `createHostContext`. Not themselves agent-exposed (no `agent`
-* field) — they power the MCP adapter and any future agent CLI.
+* field); they power the MCP adapter and any future agent CLI.
 */
 const BUILTIN_AGENT_RPC = [
 	defineRpcFunction({
@@ -1169,7 +1242,7 @@ function createScopedNodeContext(context, namespace) {
 * Framework- and build-tool-agnostic core of the Devframe node context.
 * Wires the RPC host, view (HTTP file-serving) host, diagnostics, and
 * agent subsystems. Host adapters can wrap this to augment `ctx` with
-* extra surfaces — for example, `@vitejs/devtools-kit`'s
+* extra surfaces; for example, `@vitejs/devtools-kit`'s
 * `createKitContext` attaches `docks`, `terminals`, `messages`, and
 * `commands` when mounted into Vite DevTools.
 */

package/dist/{context-DftYyXaR.d.mts → context-BJiKJqyW.d.mts}

@@ -1,4 +1,4 @@
-import { k as SharedState, o as DevframeNodeContext } from "./context-CLF4-8Pp.mjs";
+import { k as SharedState, o as DevframeNodeContext } from "./context-CHW4BZOj.mjs";
 //#region src/node/hub-internals/context.d.ts
 interface InternalAnonymousAuthStorage {
   trusted: Record<string, {
@@ -10,7 +10,7 @@ interface InternalAnonymousAuthStorage {
 }
 interface RemoteTokenRecord {
   dockId: string;
-  /** Dock URL origin — matched against WS handshake `Origin` header when `originLock` is on. */
+  /** Dock URL origin, matched against WS handshake `Origin` header when `originLock` is on. */
   origin: string;
   originLock: boolean;
 }
@@ -24,7 +24,7 @@ interface DevframeInternalContext {
    */
   revokeAuthToken: (token: string) => Promise<void>;
   /**
-   * Session-only tokens issued to remote-UI iframe docks. Not persisted —
+   * Session-only tokens issued to remote-UI iframe docks. Not persisted;
    * regenerated on every dev-server restart.
    */
   remoteTokens: Map<string, RemoteTokenRecord>;
@@ -45,8 +45,8 @@ interface DevframeInternalContext {
     url: string;
   };
   /**
-   * Set {@link DevframeInternalContext.wsEndpoint} and notify subscribers —
-   * the WS-binding tiers (side-car, shared-server, and the `unbound` tier's
+   * Set {@link DevframeInternalContext.wsEndpoint} and notify subscribers.
+   * The WS-binding tiers (side-car, shared-server, and the `unbound` tier's
    * `attach()`) call this once the socket is bound (or `undefined` once torn
    * down) instead of assigning the field directly, so anything that already
    * projected the endpoint (a hub's remote-dock URLs, registered before an