devframe 0.9.0 → 0.9.2

package/dist/constants.d.mts

@@ -1,3 +1,69 @@
+//#region src/events.d.ts
+/**
+ * Centralized registry of the core devframe event names — the node-side host
+ * bus events, the client RPC connection events, and the server→client
+ * broadcast notifications — so these names live in one place instead of
+ * scattered string literals.
+ *
+ * **Keep this in sync with [`docs/guide/events.md`](../../../docs/guide/events.md)**
+ * (the "Core devframe events" section): every name here appears in that page's
+ * tables, and every name there resolves to an entry here. Add, rename, or
+ * remove a name in both places in the same change, and reference
+ * `DEVFRAME_EVENTS.*` from call sites instead of re-typing a literal.
+ *
+ * This map covers **notifications** (events, broadcasts). The request/response
+ * RPC endpoints of the shared-state, streaming, and auth-handshake protocols
+ * (`devframe:rpc:server-state:*`, `devframe:streaming:subscribe`,
+ * `anonymous:devframe:auth`, …) are defined at their handlers and typed in
+ * `types/rpc-augments.ts`; they aren't events and stay out of this map.
+ *
+ * The `EventEmitter` maps (`RpcClientEvents`, `DevframeAgentHostEvents`) and the
+ * `DevframeRpcClientFunctions` augmentation declare these names as type-level
+ * keys (a literal is unavoidable in a type position); those declarations mirror
+ * this map and move with it.
+ */
+declare const DEVFRAME_EVENTS: {
+  /**
+   * Node-side host `EventEmitter` events. The agent host (`ctx.agent.events`)
+   * emits these as its tool/resource surface changes; protocol adapters (e.g.
+   * MCP) subscribe to re-publish their manifest.
+   */
+  readonly bus: {
+    readonly agentManifestChanged: "agent:manifest:changed";
+    readonly agentToolRegistered: "agent:tool:registered";
+    readonly agentToolUnregistered: "agent:tool:unregistered";
+    readonly agentResourceRegistered: "agent:resource:registered";
+    readonly agentResourceUnregistered: "agent:resource:unregistered";
+  };
+  /**
+   * Client-side RPC connection `EventEmitter` events (`rpc.events`) a UI
+   * subscribes to for connection lifecycle and error surfacing.
+   */
+  readonly client: {
+    readonly isTrustedUpdated: "rpc:is-trusted:updated";
+    readonly error: "rpc:error";
+    readonly connectionStatus: "connection:status";
+    readonly connectionError: "connection:error";
+  };
+  /**
+   * Broadcast notifications the server pushes to clients (server → client),
+   * `devframe:` prefix. The paired request methods (subscribe/get/set/…) are
+   * RPC endpoints, not events, and are omitted deliberately.
+   */
+  readonly broadcast: {
+    readonly authRevoked: "devframe:auth:revoked";
+    readonly clientStateUpdated: "devframe:rpc:client-state:updated";
+    readonly clientStatePatch: "devframe:rpc:client-state:patch";
+    readonly streamingChunk: "devframe:streaming:chunk";
+    readonly streamingEnd: "devframe:streaming:end";
+    readonly streamingUploadCancel: "devframe:streaming:upload-cancel";
+  };
+  /** `postMessage` channels the runtime posts across window boundaries. */
+  readonly postMessage: {
+    readonly remoteAssetsError: "devframe:remote-assets-error";
+  };
+};
+//#endregion
 //#region src/constants.d.ts
 declare const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 /**
@@ -40,6 +106,12 @@ declare const DEVFRAME_MCP_ROUTE = "__mcp";
 declare const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME = "__rpc-dump/index.json";
 declare const DEVFRAME_DOCK_IMPORTS_FILENAME = "__client-imports.js";
 declare const DEVFRAME_RPC_DUMP_DIRNAME = "__rpc-dump";
+/**
+ * Shared-state key carrying the wire-service advertisements (package name →
+ * `DevframeServiceMeta`). Written by the node services host; mirrored to
+ * clients for feature-detection via `client.services`.
+ */
+declare const DEVFRAME_SERVICES_STATE_KEY = "devframe:services";
 /**
  * URL fragment / query parameter name carrying the remote dock
  * connection descriptor (defined as `RemoteConnectionInfo` in
@@ -77,7 +149,7 @@ declare const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin
  * (`@devframes/hub-ui` does, in its iframe view). Payload shape:
  * `RemoteAssetsErrorMessage` (`devframe/types`).
  */
-declare const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE = "devframe:remote-assets-error";
+declare const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE: string;
 /**
  * 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
@@ -94,4 +166,4 @@ declare const ANONYMOUS_RPC_PREFIX = "anonymous:";
  */
 declare function isAnonymousRpcMethod(name: string): boolean;
 //#endregion
-export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_KEY, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_MCP_ROUTE, DEVFRAME_OTP_URL_PARAM, DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE, 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 };
+export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_KEY, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_EVENTS, DEVFRAME_MCP_ROUTE, DEVFRAME_OTP_URL_PARAM, DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_SERVICES_STATE_KEY, 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,3 +1,4 @@
+import { t as DEVFRAME_EVENTS } from "./events-DKfSmoTj.mjs";
 //#region src/constants.ts
 const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 /**
@@ -41,6 +42,12 @@ const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME = "__rpc-dump/index.json";
 const DEVFRAME_DOCK_IMPORTS_FILENAME = "__client-imports.js";
 const DEVFRAME_RPC_DUMP_DIRNAME = "__rpc-dump";
 /**
+* Shared-state key carrying the wire-service advertisements (package name →
+* `DevframeServiceMeta`). Written by the node services host; mirrored to
+* clients for feature-detection via `client.services`.
+*/
+const DEVFRAME_SERVICES_STATE_KEY = "devframe:services";
+/**
 * URL fragment / query parameter name carrying the remote dock
 * connection descriptor (defined as `RemoteConnectionInfo` in
 * `@vitejs/devtools-kit`) injected into remote-UI iframe dock URLs.
@@ -77,7 +84,7 @@ const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin_token";
 * (`@devframes/hub-ui` does, in its iframe view). Payload shape:
 * `RemoteAssetsErrorMessage` (`devframe/types`).
 */
-const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE = "devframe:remote-assets-error";
+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
@@ -96,4 +103,4 @@ 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_DOCK_IMPORTS_FILENAME, DEVFRAME_MCP_ROUTE, DEVFRAME_OTP_URL_PARAM, DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE, 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 };
+export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_KEY, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_EVENTS, DEVFRAME_MCP_ROUTE, DEVFRAME_OTP_URL_PARAM, DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_SERVICES_STATE_KEY, 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-xdynGSLP.mjs → context-af2w_F0_.mjs}

@@ -1,6 +1,6 @@
 import { n as randomToken } from "./crypto-token-XCqTSMg9.mjs";
-import { t as createStorage } from "./storage-CYye7P7L.mjs";
-import { n as revokeAuthToken, t as revokeActiveConnectionsForToken } from "./revoke-DZbJ7Cl0.mjs";
+import { t as createStorage } from "./storage-BNqSAOxA.mjs";
+import { n as revokeAuthToken, t as revokeActiveConnectionsForToken } from "./revoke-3Q6aDKWk.mjs";
 import { join } from "pathe";
 //#region src/node/hub-internals/context.ts
 const internalContextMap = /* @__PURE__ */ new WeakMap();

package/dist/{context-B3YUu_95.d.mts → context-al99DDJ8.d.mts}

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

package/dist/{context-CEe4PBz1.mjs → context-riPPHGiu.mjs}

@@ -2,13 +2,18 @@ import { i as defineDiagnostics } from "./nostics-CzECRXpE.mjs";
 import { t as diagnostics } from "./diagnostics-CD8nlgll.mjs";
 import { RpcFunctionsCollectorBase } from "./rpc/index.mjs";
 import { defineRpcFunction } from "./index.mjs";
-import { t as diagnostics$1 } from "./diagnostics-DOQPnQmX.mjs";
-import { r as createEventEmitter, t as DevframeAgentHost } from "./host-agent-xLCSe65D.mjs";
-import { n as createDebug, t as resolveStaticAssetsSource } from "./remote-assets-nTTxY2MU.mjs";
-import { t as createStorage } from "./storage-CYye7P7L.mjs";
+import { t as DEVFRAME_EVENTS } from "./events-DKfSmoTj.mjs";
+import { DEVFRAME_SERVICES_STATE_KEY } from "./constants.mjs";
+import { t as diagnostics$1 } from "./diagnostics-DI1HGj2I.mjs";
+import { r as createEventEmitter, t as DevframeAgentHost } from "./host-agent-DVDLqjvj.mjs";
+import { n as createDebug, t as resolveStaticAssetsSource } from "./remote-assets-CqxiyltC.mjs";
+import { t as createStorage } from "./storage-BNqSAOxA.mjs";
+import { createRequire } from "node:module";
 import { createSharedState } from "devframe/utils/shared-state";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { isAbsolute, join } from "pathe";
 import { existsSync } from "node:fs";
-import { join } from "pathe";
 //#region src/node/host-diagnostics.ts
 var DevframeDiagnosticsHost = class {
 	context;
@@ -25,7 +30,7 @@ var DevframeDiagnosticsHost = class {
 };
 //#endregion
 //#region src/node/rpc-shared-state.ts
-const debug$1 = createDebug("devframe:rpc:state:changed");
+const debug$2 = createDebug("devframe:rpc:state:changed");
 const debugSubscribe = createDebug("devframe:rpc:state:subscribe");
 function createRpcSharedStateServerHost(rpc) {
 	const sharedState = /* @__PURE__ */ new Map();
@@ -35,12 +40,12 @@ function createRpcSharedStateServerHost(rpc) {
 		const offs = [];
 		offs.push(state.on("updated", (fullState, patches, syncId) => {
 			if (patches) {
-				debug$1("patch", {
+				debug$2("patch", {
 					key,
 					syncId
 				});
 				rpc.broadcast({
-					method: "devframe:rpc:client-state:patch",
+					method: DEVFRAME_EVENTS.broadcast.clientStatePatch,
 					args: [
 						key,
 						patches,
@@ -49,12 +54,12 @@ function createRpcSharedStateServerHost(rpc) {
 					filter: (client) => client.$meta.subscribedStates.has(key)
 				});
 			} else {
-				debug$1("updated", {
+				debug$2("updated", {
 					key,
 					syncId
 				});
 				rpc.broadcast({
-					method: "devframe:rpc:client-state:updated",
+					method: DEVFRAME_EVENTS.broadcast.clientStateUpdated,
 					args: [
 						key,
 						fullState,
@@ -72,7 +77,7 @@ function createRpcSharedStateServerHost(rpc) {
 		get: async (key, options) => {
 			if (sharedState.has(key)) return sharedState.get(key);
 			if (options?.initialValue === void 0 && options?.sharedState === void 0) throw diagnostics$1.DF0013({ key });
-			debug$1("new-state", key);
+			debug$2("new-state", key);
 			const state = options.sharedState ?? createSharedState({
 				initialValue: options.initialValue,
 				enablePatches: false
@@ -402,7 +407,7 @@ function toErrorPayload(reason) {
 }
 //#endregion
 //#region src/node/rpc-streaming.ts
-const debug = createDebug("devframe:rpc:streaming");
+const debug$1 = createDebug("devframe:rpc:streaming");
 const STREAM_KEY_SEPARATOR = "";
 function streamKey(channel, id) {
 	return `${channel}${STREAM_KEY_SEPARATOR}${id}`;
@@ -427,7 +432,7 @@ function createRpcStreamingServerHost(rpc) {
 		}
 		for (const off of record.unbinders) off();
 		state.streams.delete(id);
-		debug("freed", state.name, id);
+		debug$1("freed", state.name, id);
 	}
 	function maybeFreeStream(state, id) {
 		const record = state.streams.get(id);
@@ -476,7 +481,7 @@ function createRpcStreamingServerHost(rpc) {
 			cancelRetention(record);
 			const afterSeq = opts?.afterSeq ?? 0;
 			for (const buffered of record.sink.buffer) if (buffered.seq > afterSeq) rpc.broadcast({
-				method: "devframe:streaming:chunk",
+				method: DEVFRAME_EVENTS.broadcast.streamingChunk,
 				args: [
 					channelName,
 					id,
@@ -488,7 +493,7 @@ function createRpcStreamingServerHost(rpc) {
 				filter: (client) => client.$meta === session.meta
 			});
 			if (record.sink.closed) rpc.broadcast({
-				method: "devframe:streaming:end",
+				method: DEVFRAME_EVENTS.broadcast.streamingEnd,
 				args: [
 					channelName,
 					id,
@@ -589,7 +594,7 @@ function createRpcStreamingServerHost(rpc) {
 			state.streams.set(sink.id, record);
 			record.unbinders.push(sink.events.on("chunk", (seq, chunk) => {
 				rpc.broadcast({
-					method: "devframe:streaming:chunk",
+					method: DEVFRAME_EVENTS.broadcast.streamingChunk,
 					args: [
 						name,
 						sink.id,
@@ -603,7 +608,7 @@ function createRpcStreamingServerHost(rpc) {
 			}));
 			record.unbinders.push(sink.events.on("end", (error) => {
 				rpc.broadcast({
-					method: "devframe:streaming:end",
+					method: DEVFRAME_EVENTS.broadcast.streamingEnd,
 					args: [
 						name,
 						sink.id,
@@ -636,7 +641,7 @@ function createRpcStreamingServerHost(rpc) {
 					const targetMeta = inboundRecord?.uploaderMeta;
 					if (!targetMeta) return;
 					rpc.broadcast({
-						method: "devframe:streaming:upload-cancel",
+						method: DEVFRAME_EVENTS.broadcast.streamingUploadCancel,
 						args: [name, reader.id],
 						event: true,
 						optional: true,
@@ -646,7 +651,7 @@ function createRpcStreamingServerHost(rpc) {
 			});
 			inboundRecord = { reader };
 			state.inbound.set(reader.id, inboundRecord);
-			debug("opened-inbound", name, reader.id);
+			debug$1("opened-inbound", name, reader.id);
 			return reader;
 		}
 		return {
@@ -758,15 +763,190 @@ var RpcFunctionsHostImpl = class extends RpcFunctionsCollectorBase {
 	}
 };
 //#endregion
+//#region src/node/services-install.ts
+/**
+* Turn a `resolveFrom` value (a file path, a file URL like `import.meta.url`,
+* or a directory) into something `createRequire` accepts — a directory gets a
+* synthetic filename appended so resolution starts inside it.
+*/
+function toRequireBase(resolveFrom) {
+	if (resolveFrom.startsWith("file://")) return resolveFrom;
+	if ((resolveFrom.split(/[/\\]/).pop() ?? "").includes(".")) return resolveFrom;
+	return join(resolveFrom, "_devframe_resolve.js");
+}
+/**
+* Normalize an `install()` `resolveFrom` into a resolution base. Paths and
+* file URLs pass through (the common case: the declaring plugin's
+* `importMetaUrl`, so a service it declares resolves against the plugin's own
+* dependencies); a bare npm package name resolves to that package's location
+* from `cwd`. An unresolvable package name reads as no base (the caller's
+* workspace fallbacks apply).
+*/
+function expandResolveFrom(resolveFrom, cwd) {
+	if (resolveFrom.startsWith("file://") || resolveFrom.startsWith(".") || isAbsolute(resolveFrom)) return resolveFrom;
+	const require = createRequire(join(cwd, "_devframe_resolve.js"));
+	try {
+		return require.resolve(`${resolveFrom}/package.json`);
+	} catch {}
+	try {
+		return require.resolve(resolveFrom);
+	} catch {}
+}
+/**
+* Import a service package's module, trying each `resolveFrom` candidate in
+* order (so a plugin-declared service resolves against the plugin's own
+* dependency tree first, then the workspace fallback). Throws the last
+* resolution error when no candidate succeeds.
+*/
+async function importServicePackage(pkg, resolveFroms) {
+	const candidates = [...new Set(resolveFroms.filter((x) => typeof x === "string" && x.length > 0))];
+	let lastError = /* @__PURE__ */ new Error(`no resolution base available for "${pkg}"`);
+	for (const from of candidates) {
+		let resolved;
+		try {
+			resolved = createRequire(toRequireBase(from)).resolve(pkg);
+		} catch (error) {
+			lastError = error;
+			continue;
+		}
+		return await import(pathToFileURL(resolved).href);
+	}
+	throw lastError;
+}
+function parseVersion(input) {
+	const [core, ...prerelease] = input.trim().replace(/^v/, "").split("-");
+	if (!core) return void 0;
+	const parts = core.split(".").map((part) => Number.parseInt(part, 10));
+	if (parts.length === 0 || parts.some((part) => Number.isNaN(part) || part < 0)) return void 0;
+	while (parts.length < 3) parts.push(0);
+	return {
+		parts,
+		...prerelease.length ? { prerelease: prerelease.join("-") } : {}
+	};
+}
+function compareVersions(a, b) {
+	for (let i = 0; i < 3; i++) {
+		const diff = (a.parts[i] ?? 0) - (b.parts[i] ?? 0);
+		if (diff !== 0) return diff;
+	}
+	if (a.prerelease && !b.prerelease) return -1;
+	if (!a.prerelease && b.prerelease) return 1;
+	if (a.prerelease && b.prerelease) return a.prerelease < b.prerelease ? -1 : a.prerelease > b.prerelease ? 1 : 0;
+	return 0;
+}
+function satisfiesComparator(version, comparator) {
+	const raw = comparator.trim();
+	if (!raw || raw === "*" || raw === "x") return true;
+	const operatorMatch = raw.match(/^([\^~]|>=|<=|[><=])?(.+)$/);
+	if (!operatorMatch) return false;
+	const operator = operatorMatch[1];
+	const rest = operatorMatch[2].trim();
+	const segments = rest.replace(/\.[x*]/gi, "").split(".").filter(Boolean);
+	const base = parseVersion(rest.replace(/[x*]/gi, "0"));
+	if (!base) return false;
+	switch (operator) {
+		case ">": return compareVersions(version, base) > 0;
+		case ">=": return compareVersions(version, base) >= 0;
+		case "<": return compareVersions(version, base) < 0;
+		case "<=": return compareVersions(version, base) <= 0;
+		case "^": {
+			if (compareVersions(version, base) < 0) return false;
+			const fixedIndex = base.parts.findIndex((part) => part !== 0);
+			const lockUpTo = fixedIndex === -1 ? base.parts.length - 1 : fixedIndex;
+			for (let i = 0; i <= lockUpTo; i++) if ((version.parts[i] ?? 0) !== (base.parts[i] ?? 0)) return false;
+			return true;
+		}
+		case "~": {
+			if (compareVersions(version, base) < 0) return false;
+			const lockUpTo = segments.length >= 2 ? 1 : 0;
+			for (let i = 0; i <= lockUpTo; i++) if ((version.parts[i] ?? 0) !== (base.parts[i] ?? 0)) return false;
+			return true;
+		}
+		default:
+			for (let i = 0; i < Math.max(segments.length, 3); i++) if (i < segments.length && (version.parts[i] ?? 0) !== (base.parts[i] ?? 0)) return false;
+			return segments.length >= 3 ? compareVersions(version, base) === 0 : true;
+	}
+}
+/**
+* Pragmatic semver range check for service version declarations — supports
+* the common forms (`1.2.3`, `^1.2.3`, `~1.2`, `>=1 <3`, `1.x`, `*`, and
+* `||`-joined alternatives) without pulling in a semver dependency. An
+* unparseable version or range reads as **not satisfied**.
+*/
+function satisfiesVersionRange(version, range) {
+	const parsed = parseVersion(version);
+	if (!parsed) return false;
+	const alternatives = range.split("||").map((alt) => alt.trim()).filter(Boolean);
+	if (alternatives.length === 0) return true;
+	return alternatives.some((alternative) => alternative.split(/\s+/).every((comparator) => satisfiesComparator(parsed, comparator)));
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Deep-merge two values with the service option-set rules (see below). */
+function deepMergeTwo(a, b) {
+	if (Array.isArray(a) && Array.isArray(b)) return [.../* @__PURE__ */ new Set([...a, ...b])];
+	if (isPlainObject(a) && isPlainObject(b)) {
+		const out = { ...a };
+		for (const key of Object.keys(b)) out[key] = key in a ? deepMergeTwo(a[key], b[key]) : b[key];
+		return out;
+	}
+	return b;
+}
+/**
+* Default option-set merge when a service declares no `mergeOptions`:
+* deep-merge in declaration order — objects recurse, arrays union-dedupe,
+* scalars take the later value. Covers the built-in services (`roots` /
+* `langs` union, `themes` per-key last-wins) without a custom hook.
+*/
+function deepMergeOptionSets(sets) {
+	return sets.reduce((merged, set) => deepMergeTwo(merged, set));
+}
+//#endregion
 //#region src/node/host-services.ts
+const debug = createDebug("devframe:services");
+function isServiceDefinition(input) {
+	return typeof input.setup === "function";
+}
+function validateServiceInput(input) {
+	if (!input || typeof input.package !== "string" || input.package.length === 0) throw diagnostics$1.DF0070({
+		package: String(input?.package ?? input),
+		reason: "the input has no `package` name"
+	});
+	if (isServiceDefinition(input)) validateServiceDefinition(input);
+}
+function validateServiceDefinition(def) {
+	if (typeof def.version !== "string" || def.version.length === 0) throw diagnostics$1.DF0070({
+		package: def.package,
+		reason: "the definition has no `version`"
+	});
+	if (typeof def.scope !== "string" || def.scope.length === 0) throw diagnostics$1.DF0070({
+		package: def.package,
+		reason: "the definition has no RPC `scope` namespace"
+	});
+}
 /**
 * 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.
+*
+* 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
+* 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.
 */
 var DevframeServicesHostImpl = class {
+	context;
 	services = /* @__PURE__ */ new Map();
 	listeners = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new Map();
+	installed = /* @__PURE__ */ new Map();
+	readyPromise;
+	constructor(context) {
+		this.context = context;
+	}
 	provide(id, service) {
 		const key = id;
 		if (this.services.has(key)) throw diagnostics$1.DF0037({ id: key });
@@ -799,20 +979,152 @@ var DevframeServicesHostImpl = class {
 	keys() {
 		return Array.from(this.services.keys());
 	}
+	install(input, options) {
+		validateServiceInput(input);
+		const promise = new Promise((resolve, reject) => {
+			const entry = {
+				input,
+				resolveFrom: options?.resolveFrom,
+				resolve,
+				reject
+			};
+			if (this.readyPromise) this.flushPackage(input.package, [entry]).catch(() => {});
+			else {
+				let entries = this.pending.get(input.package);
+				if (!entries) {
+					entries = [];
+					this.pending.set(input.package, entries);
+				}
+				entries.push(entry);
+			}
+		});
+		promise.catch(() => {});
+		return promise;
+	}
+	ready() {
+		if (this.readyPromise) return this.readyPromise;
+		this.readyPromise = this.flushAll();
+		return this.readyPromise;
+	}
+	async flushAll() {
+		if (this.context) await this.advertisementState();
+		const groups = Array.from(this.pending.entries());
+		this.pending.clear();
+		for (const [pkg, entries] of groups) await this.flushPackage(pkg, entries);
+	}
+	async flushPackage(pkg, entries) {
+		try {
+			const api = await this.installPackage(pkg, entries);
+			for (const entry of entries) entry.resolve(api);
+			return api;
+		} catch (error) {
+			for (const entry of entries) entry.reject(error);
+			throw error;
+		}
+	}
+	async installPackage(pkg, entries) {
+		if (this.installed.has(pkg)) {
+			diagnostics$1.DF0066({ package: pkg });
+			return this.installed.get(pkg);
+		}
+		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({
+				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);
+		}
+		for (const entry of entries) {
+			const descriptor = entry.input;
+			if (isServiceDefinition(entry.input) || typeof descriptor.version !== "string") continue;
+			if (satisfiesVersionRange(def.version, descriptor.version)) continue;
+			if (descriptor.required === true) throw diagnostics$1.DF0068({
+				package: pkg,
+				required: descriptor.version,
+				installed: def.version
+			});
+			diagnostics$1.DF0069({
+				package: pkg,
+				required: descriptor.version,
+				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: {} });
+	}
+	async advertise(def) {
+		const state = await this.advertisementState();
+		const { package: pkg, version, scope, meta } = def;
+		state.mutate((value) => {
+			value[pkg] = {
+				package: pkg,
+				version,
+				scope,
+				...meta ? { meta } : {}
+			};
+		});
+	}
 };
 //#endregion
 //#region src/node/host-views.ts
 var DevframeViewHost = class {
 	context;
+	importMetaUrl;
 	/**
 	* @internal
 	*/
 	buildStaticDirs = [];
-	constructor(context) {
+	constructor(context, importMetaUrl) {
 		this.context = context;
+		this.importMetaUrl = importMetaUrl;
 	}
-	hostStatic(baseUrl, source) {
-		const resolved = resolveStaticAssetsSource(source, this.context.host.getStorageDir("project"));
+	hostStatic(baseUrl, source, defaultResolveFrom = this.importMetaUrl) {
+		const resolved = resolveStaticAssetsSource(source, this.context.host.getStorageDir("project"), defaultResolveFrom);
 		if (typeof resolved === "string" && !existsSync(resolved)) throw diagnostics$1.DF0008({ distDir: resolved });
 		this.buildStaticDirs.push({
 			baseUrl,
@@ -900,7 +1212,8 @@ function createNodeSettingsStore(context, namespace, scope) {
 	let statePromise;
 	function store() {
 		if (!statePromise) {
-			const filepath = join(context.host.getStorageDir(STORAGE_SCOPE[scope]), "settings", `${namespace}.json`);
+			const dir = context.host.getStorageDir(STORAGE_SCOPE[scope]);
+			const filepath = join(dir, "settings", `${namespace}.json`);
 			statePromise = context.rpc.sharedState.get(stateKey, { sharedState: createStorage({
 				filepath,
 				initialValue: {}
@@ -1003,7 +1316,7 @@ function createScopedNodeContext(context, namespace) {
 * `commands` when mounted into Vite DevTools.
 */
 async function createHostContext(options) {
-	const { cwd, workspaceRoot = cwd, mode, host, builtinRpcDeclarations = [] } = options;
+	const { cwd, workspaceRoot = cwd, mode, host, importMetaUrl, builtinRpcDeclarations = [] } = options;
 	const context = {
 		cwd,
 		workspaceRoot,
@@ -1018,12 +1331,12 @@ async function createHostContext(options) {
 		scope: void 0
 	};
 	const rpcHost = new RpcFunctionsHostImpl(context);
-	const viewsHost = new DevframeViewHost(context);
+	const viewsHost = new DevframeViewHost(context, importMetaUrl);
 	const diagnosticsHost = new DevframeDiagnosticsHost(context, [diagnostics$1, diagnostics]);
 	context.rpc = rpcHost;
 	context.views = viewsHost;
 	context.diagnostics = diagnosticsHost;
-	context.services = new DevframeServicesHostImpl();
+	context.services = new DevframeServicesHostImpl(context);
 	context.agent = new DevframeAgentHost(context);
 	const scopedCache = /* @__PURE__ */ new Map();
 	context.scope = ((namespace) => {