devframe 0.9.8 → 0.9.9

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

@@ -1,13 +1,13 @@
-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 { t as diagnostics } from "./diagnostics-D0EVm5M6.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-BMfN8mb1.mjs";
+import { a as DevframeAgentHost, i as satisfiesVersionRange, n as expandResolveFrom, r as importServicePackage, s as createEventEmitter, t as deepMergeOptionSets } from "./services-install-P_DV7VYL.mjs";
+import { n as createDebug, t as resolveStaticAssetsSource } from "./remote-assets-BIFWOlBW.mjs";
+import { t as createStorage } from "./storage-Dccf_IyD.mjs";
 import { createSharedState } from "devframe/utils/shared-state";
 import process from "node:process";
 import { join } from "pathe";
@@ -17,6 +17,10 @@ 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,6 +127,10 @@ function createRpcSharedStateServerHost(rpc) {
 			if (!sharedState.has(key)) return void 0;
 			return (await host.get(key)).value();
 		},
+		/**
+		* Pre-compute snapshots for the build-mode static dump so the SPA
+		* can read them without a live server.
+		*/
 		dump: () => ({ inputs: host.keys().map((key) => [key]) })
 	});
 	rpc.register({
@@ -158,7 +166,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 +237,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 +420,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 +581,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 +681,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);
 		}
 	};
 }
@@ -784,13 +798,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.
@@ -887,42 +912,68 @@ var DevframeServicesHostImpl = class {
 		}
 		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(def.package, 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 +989,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 +1057,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 +1207,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-KUqAfawQ.mjs → context-DIUvJW4D.mjs}

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

package/dist/{context-DftYyXaR.d.mts → context-rgBSPFHS.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-4AIVRLYF.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

package/dist/{crypto-token-XCqTSMg9.mjs → crypto-token-TVbGGFuj.mjs}

@@ -2,7 +2,7 @@
 const HEX = "0123456789abcdef";
 /**
 * Generate a high-entropy, URL-safe (hex) random token suitable for use as a
-* bearer credential — e.g. the persistent client auth token or an ephemeral
+* bearer credential, e.g. the persistent client auth token or an ephemeral
 * remote-dock token. Defaults to 16 bytes (128 bits) of entropy.
 */
 function randomToken(byteLength = 16) {

package/dist/{dev-CzkPCJwi.mjs → dev-Eqq5PX0k.mjs}

@@ -1,17 +1,17 @@
-import { t as resolveClientAssets } from "./client-assets-C7SXgTWY.mjs";
+import { t as resolveClientAssets } from "./client-assets-DNdhagGm.mjs";
 import { DEVFRAME_CONNECTION_META_FILENAME } from "./constants.mjs";
-import { t as diagnostics } from "./diagnostics-BXWW3VK-.mjs";
-import { t as createHostContext } from "./context-omlma_1n.mjs";
-import { t as resolveStaticAssetsSource } from "./remote-assets-DezQmPQU.mjs";
-import { i as resolveMcpConnectionMeta, n as resolveBasePath, r as resolveDevServerPort, t as normalizeBasePath } from "./_shared-BM3PdYli.mjs";
-import { t as createH3DevframeHost } from "./host-h3-fRbF9yor.mjs";
-import { a as importRuntimeModule, i as normalizeHttpServerUrl, n as resolveInstanceRegister, t as createInstanceShell } from "./instance-shell-CpVW4zG0.mjs";
+import { t as diagnostics } from "./diagnostics-BMfN8mb1.mjs";
+import { t as createHostContext } from "./context-CwPUinjn.mjs";
+import { t as resolveStaticAssetsSource } from "./remote-assets-BIFWOlBW.mjs";
+import { i as resolveMcpConfig, n as resolveBasePath, r as resolveDevServerPort, t as normalizeBasePath } from "./_shared-C08SdQRl.mjs";
+import { t as createH3DevframeHost } from "./host-h3-BJ4siyz7.mjs";
+import { a as importRuntimeModule, i as normalizeHttpServerUrl, n as resolveInstanceRegister, t as createInstanceShell } from "./instance-shell-cdVETpfz.mjs";
 import { open } from "./utils/open.mjs";
 import { mountStaticHandler } from "./utils/serve-static.mjs";
 import { createServer } from "node:http";
 import process from "node:process";
 import { resolve } from "pathe";
-import { joinURL, withBase } from "ufo";
+import { joinURL, withBase, withoutLeadingSlash } from "ufo";
 import { H3, toNodeHandler } from "h3";
 //#region src/adapters/initiate.ts
 const INSTANCE_INTERNALS = /* @__PURE__ */ new WeakMap();
@@ -20,7 +20,7 @@ function getInstanceInternals(handler) {
 	return INSTANCE_INTERNALS.get(handler) ?? {};
 }
 /**
-* Serve a devframe through one framework-agnostic, web-standard 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
@@ -28,10 +28,10 @@ function getInstanceInternals(handler) {
 *
 * 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
+* 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
+* {@link DevframeInstance.attach}. Meanwhile `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.
@@ -46,6 +46,10 @@ function initDevframe(def, options) {
 		app,
 		host,
 		origin: options.origin,
+		/**
+		* Auth resolution mirrors `createDevServer`: gate by default, explicit
+		* `false` opts out, a handler object installs a custom scheme.
+		*/
 		auth: options.auth !== void 0 ? options.auth : def.cli?.auth,
 		server: options.server,
 		ws: options.ws ?? def.cli?.ws,
@@ -84,12 +88,13 @@ function initDevframe(def, options) {
 			for (const input of def.services ?? []) context.services.install(input, { resolveFrom: def.importMetaUrl });
 			await context.services.ready();
 			await def.setup(context, setupInfo);
-			const mcpOption = options.mcp ?? def.cli?.mcp;
-			const mcpMeta = resolveMcpConnectionMeta(def, mcpOption);
+			const mcpConfig = resolveMcpConfig(options.mcp ?? def.cli?.mcp);
+			let mcpMeta;
 			let mcpDispose;
-			if (mcpMeta) {
-				const mcpConfig = mcpOption === true || mcpOption === void 0 ? {} : mcpOption;
-				const mcpPath = joinURL(base, mcpMeta.path);
+			if (mcpConfig) {
+				const mcpRoute = withoutLeadingSlash(mcpConfig.path ?? "__mcp");
+				mcpMeta = { path: mcpRoute };
+				const mcpPath = joinURL(base, mcpRoute);
 				let mountMcpHttp;
 				try {
 					({mountMcpHttp} = await importRuntimeModule("devframe/adapters/mcp"));
@@ -105,6 +110,7 @@ function initDevframe(def, options) {
 					serverName: `${def.id} (devframe)`,
 					serverVersion: def.version ?? "0.0.0",
 					exposeSharedState: true,
+					authorization: mcpConfig.authorization,
 					allowedOrigins: mcpConfig.allowedOrigins
 				}).dispose;
 			}
@@ -139,14 +145,14 @@ function initDevframe(def, options) {
 //#endregion
 //#region src/adapters/dev.ts
 /**
-* Start a devframe dev server for a {@link DevframeDefinition} —
+* 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 the definition's client assets are 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
+* hosted elsewhere (e.g. by a parent Vite/Nuxt dev server); see
 * `devframeViteBridge` from `@devframes/vite`.
 *
 * Returns the underlying {@link StartedServer} handle so callers can
@@ -194,12 +200,25 @@ async function createDevServer(def, options = {}) {
 		ws: options.ws,
 		allowedOrigins: options.allowedOrigins,
 		sse: options.sse,
+		/**
+		* The `--no-auth` flag forces the gate off regardless of the `auth`
+		* option / definition default (which the instance resolves itself).
+		*/
 		auth: flags.auth === false ? false : options.auth,
 		mcp: options.mcp,
 		flags,
 		onPeerConnect: options.onPeerConnect,
 		onPeerDisconnect: options.onPeerDisconnect,
+		/**
+		* Publish in the global registry so discovery tooling (`devframe connect`)
+		* finds the server without port guessing. The instance owns the record's
+		* lifecycle, written once its (pinned) origin resolves, removed on close.
+		*/
 		register: true,
+		/**
+		* This server is devframe's own, and nothing else handles its upgrades, so
+		* off-route upgrade attempts are rejected promptly.
+		*/
 		destroyUnmatchedUpgrades: true
 	});
 	try {

package/dist/{diagnostics-BXWW3VK-.mjs → diagnostics-BMfN8mb1.mjs}

@@ -1,5 +1,10 @@
-import { i as defineDiagnostics } from "./nostics-CzECRXpE.mjs";
+import { i as defineDiagnostics } from "./nostics-D0PvLZsn.mjs";
 //#region src/node/diagnostics.ts
+/**
+* DF00xx codes are allocated across packages (e.g. @devframes/json-render
+* owns DF0037–DF0041), so this file alone doesn't show the next free
+* number; check `docs/content/6.errors/` for the full allocation before adding one.
+*/
 const diagnostics = defineDiagnostics({
 	docsBase: "https://devfra.me/errors",
 	codes: {
@@ -9,7 +14,7 @@ const diagnostics = defineDiagnostics({
 		DF0012: { why: (p) => `Failed to parse storage file: ${p.filepath}, falling back to defaults.` },
 		DF0013: { why: (p) => `Shared state of "${p.key}" is not found, please provide an initial value for the first time` },
 		DF0014: {
-			why: (p) => `RPC function "${p.name}" has an invalid \`agent\` field — \`description\` must be a non-empty string.`,
+			why: (p) => `RPC function "${p.name}" has an invalid \`agent\` field: \`description\` must be a non-empty string.`,
 			fix: "Provide a short description (~1–3 sentences) explaining what the tool does and when agents should invoke it."
 		},
 		DF0015: {
@@ -23,12 +28,12 @@ const diagnostics = defineDiagnostics({
 			fix: "The consumer is too slow for the producer. Raise `highWaterMark` on the subscription, slow the producer, or batch chunks."
 		},
 		DF0030: {
-			why: (p) => `Stream "${p.channel}#${p.id}" is unknown — no producer has called \`channel.start({ id: "${p.id}" })\`.`,
+			why: (p) => `Stream "${p.channel}#${p.id}" is unknown; no producer has called \`channel.start({ id: "${p.id}" })\`.`,
 			fix: "Ensure the server-side producer is running before clients subscribe, or check for typos in the stream id."
 		},
 		DF0031: {
 			why: (p) => `Cannot write to closed stream "${p.channel}#${p.id}".`,
-			fix: "Track the producer lifecycle — guard writes with the `stream.signal.aborted` flag."
+			fix: "Track the producer lifecycle by guarding writes with the `stream.signal.aborted` flag."
 		},
 		DF0032: {
 			why: (p) => `Streaming channel "${p.channel}" is already registered.`,
@@ -48,14 +53,14 @@ const diagnostics = defineDiagnostics({
 		},
 		DF0036: {
 			why: (p) => `RPC call to "${p.name}" was rejected: the caller is not authorized.`,
-			fix: "Complete the auth handshake (or connect with a static/pre-shared token) before calling a trusted method. Untrusted callers may only call `anonymous:`-prefixed methods — see `isAnonymousRpcMethod`."
+			fix: "Complete the auth handshake (or connect with a static/pre-shared token) before calling a trusted method. Untrusted callers may only call `anonymous:`-prefixed methods; see `isAnonymousRpcMethod`."
 		},
 		DF0037: {
 			why: (p) => `A service is already provided under "${p.id}".`,
 			fix: "Service ids are unique per context. Revoke the existing provider first (the `provide()` call returns a revoke function), or namespace the id with your plugin id to avoid collisions."
 		},
 		DF0042: {
-			why: (p) => `"${p.id}" declares \`capabilities.build: false\` — its static export is not meaningful (writes are excluded and any live-served data won't be there).`,
+			why: (p) => `"${p.id}" declares \`capabilities.build: false\`, so its static export is not meaningful (writes are excluded and any live-served data won't be there).`,
 			fix: "Pass `{ force: true }` to `createBuild()` if the degraded export is still useful to you, or drop `capabilities.build: false` on the definition."
 		},
 		DF0045: {
@@ -80,7 +85,7 @@ const diagnostics = defineDiagnostics({
 		},
 		DF0050: {
 			why: (p) => `No running devframe instance on port ${p.port}.`,
-			fix: "Call devframe_connect_list-instances for the current instance list — the instance may have stopped or changed port."
+			fix: "Call devframe_connect_list-instances for the current instance list; the instance may have stopped or changed port."
 		},
 		DF0051: {
 			why: (p) => `The devframe instance on port ${p.port} has no MCP endpoint.`,
@@ -92,7 +97,7 @@ const diagnostics = defineDiagnostics({
 		},
 		DF0054: {
 			why: (p) => `connectionMeta() was called before initDevframe("${p.id}") finished initializing.`,
-			fix: "Await `instance.ready` (or any request through `instance.handler`) before reading `connectionMeta()` — the WebSocket binding it describes is only known once initialization completes."
+			fix: "Await `instance.ready` (or any request through `instance.handler`) before reading `connectionMeta()`; the WebSocket binding it describes is only known once initialization completes."
 		},
 		DF0055: {
 			why: (p) => `This instance already owns its WebSocket transport (${p.tier}), so it cannot take over the host's upgrade events.`,
@@ -104,10 +109,10 @@ const diagnostics = defineDiagnostics({
 		},
 		DF0057: {
 			why: () => "This instance disables its WebSocket transport (`ws: false`), so there is no socket to drive upgrades into.",
-			fix: "Clients connect over the SSE endpoint instead — no upgrade wiring is needed. Remove `ws: false` if the instance should serve a WebSocket after all."
+			fix: "Clients connect over the SSE endpoint instead, so no upgrade wiring is needed. Remove `ws: false` if the instance should serve a WebSocket after all."
 		},
 		DF0058: {
-			why: (p) => `"${p.id}" declares \`capabilities.dev: false\` — it does not support a live dev server (its value is a static export only).`,
+			why: (p) => `"${p.id}" declares \`capabilities.dev: false\`, so it does not support a live dev server (its value is a static export only).`,
 			fix: "Pass `{ force: true }` to `createDevServer()` to run it anyway, or drop `capabilities.dev: false` on the definition."
 		},
 		DF0059: {
@@ -120,10 +125,10 @@ const diagnostics = defineDiagnostics({
 		},
 		DF0061: {
 			why: (p) => `The locally installed "${p.package}@${p.installed}" is a different major version than the required "${p.required}".`,
-			fix: "Align the installed assets package with the version its node package declares — they are published in lockstep."
+			fix: "Align the installed assets package with the version its node package declares; they are published in lockstep."
 		},
 		DF0062: {
-			why: (p) => `The locally installed "${p.package}@${p.installed}" differs from the required "${p.required}" — serving the installed one.`,
+			why: (p) => `The locally installed "${p.package}@${p.installed}" differs from the required "${p.required}"; serving the installed one.`,
 			fix: "Install the exact declared version to serve byte-identical assets."
 		},
 		DF0063: {
@@ -136,10 +141,10 @@ const diagnostics = defineDiagnostics({
 		},
 		DF0065: {
 			why: (p) => `Invalid remote-assets ${p.field} "${p.value}".`,
-			fix: "A remote-assets `package` must be a valid npm package name and `version` an exact semver version (e.g. `1.2.3`) — they are interpolated into CDN URLs and the cache path."
+			fix: "A remote-assets `package` must be a valid npm package name and `version` an exact semver version (e.g. `1.2.3`); they are interpolated into CDN URLs and the cache path."
 		},
 		DF0066: {
-			why: (p) => `Service "${p.package}" is already installed — keeping the first installation and ignoring this one's options.`,
+			why: (p) => `Service "${p.package}" is already installed; keeping the first installation and ignoring this one's options.`,
 			fix: "Option sets only merge before `ctx.services.ready()` fires. Install the service (or declare it in `DevframeDefinition.services`) before the barrier so its options join the merge."
 		},
 		DF0067: {
@@ -151,16 +156,24 @@ const diagnostics = defineDiagnostics({
 			fix: "Align the installed service package with the range its declarer requires, or drop `required: true` to downgrade the mismatch to a warning."
 		},
 		DF0069: {
-			why: (p) => `The installed service "${p.package}@${p.installed}" does not satisfy the declared range "${p.required}" — installing it anyway.`,
+			why: (p) => `The installed service "${p.package}@${p.installed}" does not satisfy the declared range "${p.required}"; installing it anyway.`,
 			fix: "The advertised meta carries the real version, so clients can gate on it. Align the installed service package with the declared range to silence this warning."
 		},
 		DF0070: {
 			why: (p) => `Invalid service "${p.package}": ${p.reason}`,
-			fix: "A service package's default export must be a factory returning a `DevframeServiceDefinition` — an object with `package`, `version`, `scope`, and a `setup` function."
+			fix: "A service package's default export must be a factory returning a `DevframeServiceDefinition`, an object with `package`, `version`, `scope`, and a `setup` function."
 		},
 		DF0072: {
-			why: (p) => `\`rpc.snapshot\` names "${p.method}", but no RPC function is registered under that id — nothing to bake into the static build.`,
+			why: (p) => `\`rpc.snapshot\` names "${p.method}", but no RPC function is registered under that id, so nothing to bake into the static build.`,
 			fix: "Check the method id, and ensure the service/plugin that registers it is installed (e.g. declared in `services`) before the build collects the dump."
+		},
+		DF0075: {
+			why: (p) => `On ${p.runtime} the shared server's WebSocket upgrade needs crossws's Node adapter, which refuses to run off Node, and SSE is disabled, so this instance advertises no RPC transport at all.`,
+			fix: "Keep the SSE endpoint enabled (drop `sse: false`) so clients connect over it on Bun/Deno, or move the socket to a side-car (`ws: { sidecar: true }`) which binds the native WebSocket adapter on its own port."
+		},
+		DF0076: {
+			why: (p) => `\`attach\` / \`handleUpgrade\` drive a raw \`node:http\` upgrade into crossws's Node adapter, which refuses to run on ${p.runtime}.`,
+			fix: "On Bun/Deno, serve the advertised `__ws` route from `Bun.serve` / `Deno.serve` with `attachBunWsTransport` / `attachDenoWsTransport` (see the hub-deno-minimal example), or connect over the SSE endpoint instead."
 		}
 	}
 });

package/dist/{diagnostics-CD8nlgll.mjs → diagnostics-D0EVm5M6.mjs}

@@ -1,10 +1,10 @@
-import { i as defineDiagnostics } from "./nostics-CzECRXpE.mjs";
+import { i as defineDiagnostics } from "./nostics-D0PvLZsn.mjs";
 //#region src/rpc/diagnostics.ts
 const diagnostics = defineDiagnostics({
 	docsBase: "https://devfra.me/errors",
 	codes: {
 		DF0019: {
-			why: (p) => `RPC function "${p.name}" has \`agent\` set but \`jsonSerializable\` is not \`true\` — MCP requires JSON-serializable data.`,
+			why: (p) => `RPC function "${p.name}" has \`agent\` set but \`jsonSerializable\` is not \`true\`; MCP requires JSON-serializable data.`,
 			fix: "Set `jsonSerializable: true` if the payload is JSON-safe, or remove `agent` to keep it RPC-only."
 		},
 		DF0020: {