@devframes/hub 0.8.2 → 0.9.0-beta.10

package/dist/node/index.mjs

@@ -1,16 +1,7 @@
-import { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS } from "../constants.mjs";
-import { r as defineHubRpcFunction } from "../define-Pbx8dsKz.mjs";
-import { t as buildRemoteConnectionUrl } from "../remote-url-KVXtKP47.mjs";
-import { createEventEmitter } from "devframe/utils/events";
-import { coerceAgentPositionalArgs, createHostContext, createStorage } from "devframe/node";
-import { debounce } from "perfect-debounce";
-import { defineDiagnostics } from "nostics";
-import { colors } from "devframe/utils/colors";
-import { ansiFormatter } from "nostics/formatters/ansi";
-import { getInternalContext, resolveBasePath } from "devframe/node/hub-internals";
-import { join, resolve } from "pathe";
-import { nanoid } from "devframe/utils/nanoid";
-import process$1 from "node:process";
+import { _ as DevframeCommandsHost, a as hubMessagesAdd, c as hubMessagesUpdate, d as hubTerminalsRestart, f as hubTerminalsTerminate, g as DevframeDocksHost, h as DevframeMessagesHost, i as hubDocksActivate, l as hubTerminalsRemove, m as DevframeTerminalsHost, n as builtinHubRpcDeclarations, o as hubMessagesClear, p as hubTerminalsWrite, r as hubCommandsExecute, s as hubMessagesRemove, t as createHubContext, u as hubTerminalsResize } from "../context-DzqMQ2mI.mjs";
+import "ufo";
+import "pathe";
+import "node:process";
 import { builtinModules } from "node:module";
 import "node:fs";
 import "node:url";
@@ -18,1168 +9,6 @@ import assert from "node:assert";
 import "node:path";
 import v8 from "node:v8";
 import { format, inspect } from "node:util";
-//#region src/utils/diagnostics-reporter.ts
-const formatAnsi = ansiFormatter(colors);
-function hubReporter(d, { method = "warn" } = {}) {
-	console[method](formatAnsi(d));
-}
-//#endregion
-//#region src/node/diagnostics.ts
-const diagnostics = defineDiagnostics({
-	docsBase: "https://devfra.me/errors",
-	reporters: [hubReporter],
-	codes: {
-		DF8100: {
-			why: (p) => `Dock with id "${p.id}" is already registered`,
-			fix: "Use the `force` parameter to overwrite an existing registration."
-		},
-		DF8101: {
-			why: (p) => `Cannot change the id of dock "${p.id}" to "${p.attempted}". Dock ids are immutable once registered`,
-			fix: (p) => `Remove \`id\` from the patch to keep updating "${p.id}", or call register() with the full entry to add "${p.attempted}" as a new dock.`
-		},
-		DF8102: {
-			why: (p) => `Dock with id "${p.id}" is not registered and cannot be updated`,
-			fix: (p) => `Call register() to add "${p.id}" as a new dock, or check the id for typos.`
-		},
-		DF8103: {
-			why: (p) => `Dock entry "${p.id}" cannot set groupId to its own id`,
-			fix: "Point groupId at a different group entry, or omit it."
-		},
-		DF8104: {
-			why: (p) => `Dock group "${p.id}" cannot itself belong to a group (nested groups are unsupported)`,
-			fix: "Remove groupId from the group entry; nest members one level only."
-		},
-		DF8105: {
-			why: (p) => `Devframe "${p.name}" (id "${p.id}") is already mounted on this hub`,
-			fix: "Each devframe is deduplicated by id. Set `duplicationStrategy: \"duplicate\"` on the definition to let instances coexist, `\"silent\"` to drop duplicates quietly, or `\"throw\"` to surface them as errors."
-		},
-		DF8106: {
-			why: (p) => `The host cannot serve the RPC connection meta for devframe "${p.name}" (id "${p.id}") at "${p.base}" — its \`DevframeHost\` does not implement \`mountConnectionMeta\`.`,
-			fix: "Implement `mountConnectionMeta(base)` on your DevframeHost so it serves `__connection.json` at each mounted base. Without it, the devframe SPA connects only when it shares an origin with the hub UI (same-origin window inheritance); cross-origin, sandboxed, or directly-opened iframes stay disconnected. Static-snapshot hosts that bake the meta into the served files can implement it as a no-op to acknowledge this intentionally."
-		},
-		DF8107: {
-			why: (p) => `Dock activation requested for unknown dock id "${p.id}"`,
-			fix: "Pass a `dockId` that matches a registered dock entry. The activation is still broadcast, but no viewer will switch to it. Ids are case-sensitive — check for typos, and ensure the target dock is registered before activating it."
-		},
-		DF8200: { why: (p) => `Terminal session with id "${p.id}" already registered` },
-		DF8201: { why: (p) => `Terminal session with id "${p.id}" not registered` },
-		DF8202: {
-			why: (p) => `Terminal session "${p.id}" does not accept input`,
-			fix: "Spawn it via ctx.terminals.startPtySession() to get an interactive, writable session."
-		},
-		DF8203: { why: (p) => `Failed to spawn PTY session for "${p.command}": ${p.reason}` },
-		DF8204: {
-			why: (p) => `Terminal session "${p.id}" cannot be controlled (no lifecycle handle)`,
-			fix: "Spawn it via ctx.terminals.startChildProcess() or startPtySession() — sessions added with a bare register() expose no terminate/restart handle."
-		},
-		DF8205: {
-			why: (p) => `Terminal session "${p.id}" is not restartable`,
-			fix: "It was registered with `restartable: false`; restart it through its owner's controls, or spawn it with `restartable: true` (the default) to allow in-place restarts."
-		},
-		DF8206: {
-			why: (p) => `Terminal session "${p.id}" cannot be restarted — its output stream is already closed`,
-			fix: "The session already exited (or was terminated) and its stream is spent. Drop it with `ctx.terminals.remove(session)`, then spawn a replacement via `ctx.terminals.startChildProcess()` or `ctx.terminals.startPtySession()` with a fresh id."
-		},
-		DF8400: { why: (p) => `Command "${p.id}" is already registered` },
-		DF8401: { why: "Cannot change the id of a command. Use register() to add new commands" },
-		DF8402: { why: (p) => `Command "${p.id}" is not registered` },
-		DF8403: {
-			why: (p) => `Command id "${p.id}" is already used by another command or child command`,
-			fix: "Use globally unique command ids for top-level commands and all child commands."
-		},
-		DF8404: {
-			why: (p) => `Command "${p.id}" declares agent exposure but has no handler`,
-			fix: "Agent-exposed commands must be executable server-side. Add a `handler` to the command, or move the `agent` field to an executable child command."
-		}
-	}
-});
-//#endregion
-//#region src/node/host-commands.ts
-function findChildCommand(command, id) {
-	for (const child of command.children ?? []) {
-		if (child.id === id) return child;
-		const nested = findChildCommand(child, id);
-		if (nested) return nested;
-	}
-}
-function collectCommandIds(command, ids = []) {
-	ids.push(command.id);
-	for (const child of command.children ?? []) collectCommandIds(child, ids);
-	return ids;
-}
-function validateCommandIds(commands, command, ignoreTopLevelId) {
-	const ids = collectCommandIds(command);
-	const seen = /* @__PURE__ */ new Set();
-	for (const id of ids) {
-		if (seen.has(id)) throw diagnostics.DF8403({ id });
-		seen.add(id);
-	}
-	for (const [registeredId, registered] of commands) {
-		if (registeredId === ignoreTopLevelId) continue;
-		const registeredIds = new Set(collectCommandIds(registered));
-		for (const id of ids) if (registeredIds.has(id)) throw diagnostics.DF8403({ id });
-	}
-}
-var DevframeCommandsHost = class {
-	context;
-	commands = /* @__PURE__ */ new Map();
-	events = createEventEmitter();
-	/**
-	* Lazy agent projection: `ctx.agent` queries this provider at list/invoke
-	* time, deriving tools from {@link commands} on demand — the commands map
-	* stays the single source of truth, nothing is mirrored or kept in sync.
-	*/
-	agentProvider;
-	constructor(context) {
-		this.context = context;
-		this.agentProvider = context.agent?.registerToolProvider(() => this.collectAgentTools());
-	}
-	register(command) {
-		if (this.commands.has(command.id)) throw diagnostics.DF8400({ id: command.id });
-		validateCommandIds(this.commands, command);
-		this.validateAgentExposure(command);
-		this.commands.set(command.id, command);
-		this.events.emit("command:registered", this.toSerializable(command));
-		this.agentProvider?.notifyChanged();
-		return {
-			id: command.id,
-			update: (patch) => {
-				if ("id" in patch) throw diagnostics.DF8401();
-				const existing = this.commands.get(command.id);
-				if (!existing) throw diagnostics.DF8402({ id: command.id });
-				const next = {
-					...existing,
-					...patch,
-					id: existing.id
-				};
-				validateCommandIds(this.commands, next, existing.id);
-				this.validateAgentExposure(next);
-				Object.assign(existing, patch);
-				this.events.emit("command:registered", this.toSerializable(existing));
-				this.agentProvider?.notifyChanged();
-			},
-			unregister: () => this.unregister(command.id)
-		};
-	}
-	unregister(id) {
-		const deleted = this.commands.delete(id);
-		if (deleted) {
-			this.events.emit("command:unregistered", id);
-			this.agentProvider?.notifyChanged();
-		}
-		return deleted;
-	}
-	async execute(id, ...args) {
-		const found = this.findCommand(id);
-		if (!found) throw diagnostics.DF8402({ id });
-		if (!found.handler) throw new Error(`Command "${id}" has no handler (group-only command)`);
-		return found.handler(...args);
-	}
-	list() {
-		return Array.from(this.commands.values()).map((cmd) => this.toSerializable(cmd));
-	}
-	findCommand(id) {
-		const topLevel = this.commands.get(id);
-		if (topLevel) return topLevel;
-		for (const cmd of this.commands.values()) {
-			const child = findChildCommand(cmd, id);
-			if (child) return child;
-		}
-	}
-	toSerializable(cmd) {
-		const { handler: _, agent: __, children, ...rest } = cmd;
-		return {
-			...rest,
-			source: "server",
-			...children ? { children: children.map((c) => this.toSerializable(c)) } : {}
-		};
-	}
-	/** Reject `agent` on handler-less commands anywhere in the tree, up front. */
-	validateAgentExposure(command) {
-		if (command.agent && !command.handler) throw diagnostics.DF8404({ id: command.id });
-		for (const child of command.children ?? []) this.validateAgentExposure(child);
-	}
-	/**
-	* Derive the agent-tool projection of the current command trees: every
-	* agent-flagged, handler-bearing command (children included) becomes a
-	* callable tool. Queried lazily by the provider registered in the
-	* constructor. `when` clauses evaluate client-side only and are not
-	* enforced here — opting in a `when`-gated command is a deliberate author
-	* decision (documented on `DevframeCommandAgentOptions`).
-	*/
-	collectAgentTools() {
-		const tools = [];
-		const walk = (command) => {
-			const agent = command.agent;
-			if (agent && command.handler) tools.push({
-				id: command.id,
-				title: agent.title ?? command.title,
-				description: agent.description,
-				safety: agent.safety ?? "action",
-				tags: agent.tags,
-				args: agent.args,
-				handler: async (args) => this.execute(command.id, ...coerceAgentPositionalArgs(args, agent.args, "drop"))
-			});
-			for (const child of command.children ?? []) walk(child);
-		};
-		for (const command of this.commands.values()) walk(command);
-		return tools;
-	}
-};
-//#endregion
-//#region src/node/host-docks.ts
-function normaliseRemoteOptions(remote) {
-	const opts = remote === true ? {} : remote;
-	return {
-		transport: opts.transport ?? "fragment",
-		originLock: opts.originLock ?? true
-	};
-}
-var DevframeDocksHost = class {
-	context;
-	views = /* @__PURE__ */ new Map();
-	events = createEventEmitter();
-	userSettings = void 0;
-	/** Dock-id → allocated remote token + resolved options. */
-	remoteDocks = /* @__PURE__ */ new Map();
-	constructor(context) {
-		this.context = context;
-	}
-	async init() {
-		this.userSettings = await this.context.rpc.sharedState.get("devframe:user-settings", { sharedState: createStorage({
-			filepath: join(this.context.host.getStorageDir("project"), "settings.json"),
-			initialValue: DEFAULT_STATE_USER_SETTINGS()
-		}) });
-	}
-	values() {
-		return Array.from(this.views.values(), (view) => this.projectView(view));
-	}
-	projectView(view) {
-		if (view.type !== "iframe" || !view.remote) return view;
-		const record = this.remoteDocks.get(view.id);
-		const endpoint = getInternalContext(this.context).wsEndpoint;
-		if (!record || !endpoint) return view;
-		const payload = {
-			v: 1,
-			backend: "websocket",
-			websocket: endpoint.url,
-			authToken: record.token,
-			origin: this.resolveDevServerOrigin()
-		};
-		return {
-			...view,
-			url: buildRemoteConnectionUrl(view.url, payload, record.options.transport)
-		};
-	}
-	resolveDevServerOrigin() {
-		return this.context.host.resolveOrigin();
-	}
-	register(view, force) {
-		if (this.views.has(view.id) && !force) throw diagnostics.DF8100({ id: view.id });
-		this.validateGroupMembership(view);
-		this.prepareRemoteRegistration(view);
-		this.views.set(view.id, view);
-		this.events.emit("dock:entry:updated", view);
-		return { update: (patch) => {
-			if (patch.id && patch.id !== view.id) throw diagnostics.DF8101({
-				id: view.id,
-				attempted: patch.id
-			});
-			this.update({
-				...this.views.get(view.id),
-				...patch
-			});
-		} };
-	}
-	update(view) {
-		if (!this.views.has(view.id)) throw diagnostics.DF8102({ id: view.id });
-		this.validateGroupMembership(view);
-		this.prepareRemoteRegistration(view);
-		this.views.set(view.id, view);
-		this.events.emit("dock:entry:updated", view);
-	}
-	activate(dockId, params) {
-		if (!this.views.has(dockId)) diagnostics.DF8107({ id: dockId });
-		this.events.emit("dock:activate", {
-			dockId,
-			params
-		});
-	}
-	validateGroupMembership(view) {
-		if (view.groupId === void 0) return;
-		if (view.groupId === view.id) throw diagnostics.DF8103({ id: view.id });
-		if (view.type === "group") throw diagnostics.DF8104({ id: view.id });
-	}
-	prepareRemoteRegistration(view) {
-		const internal = getInternalContext(this.context);
-		internal.revokeRemoteTokensForDock(view.id);
-		this.remoteDocks.delete(view.id);
-		if (view.type !== "iframe" || !view.remote) return;
-		const options = normaliseRemoteOptions(view.remote);
-		let dockOrigin;
-		try {
-			dockOrigin = new URL(view.url).origin;
-		} catch {
-			dockOrigin = this.resolveDevServerOrigin();
-		}
-		const token = internal.allocateRemoteToken(view.id, dockOrigin, options.originLock);
-		this.remoteDocks.set(view.id, {
-			token,
-			options
-		});
-	}
-};
-//#endregion
-//#region src/node/host-messages.ts
-const MAX_ENTRIES = 1e3;
-const MAX_REMOVALS = 1e3;
-var DevframeMessagesHost = class {
-	context;
-	entries = /* @__PURE__ */ new Map();
-	events = createEventEmitter();
-	/** Tracks when each entry was last added or updated (monotonic) */
-	lastModified = /* @__PURE__ */ new Map();
-	/** Tracks recently removed entry IDs with their removal time */
-	removals = [];
-	_autoDeleteTimers = /* @__PURE__ */ new Map();
-	_clock = 0;
-	/**
-	* The tick of the newest removal record dropped from the capped
-	* `removals` log — cursors older than this can't get a reliable delta
-	* and fall back to a full snapshot in {@link listSince}.
-	*/
-	_removalsTrimmedAt = 0;
-	_tick() {
-		return ++this._clock;
-	}
-	_recordRemoval(id, time) {
-		this.removals.push({
-			id,
-			time
-		});
-		if (this.removals.length > MAX_REMOVALS) {
-			const dropped = this.removals.splice(0, this.removals.length - MAX_REMOVALS);
-			this._removalsTrimmedAt = dropped[dropped.length - 1].time;
-		}
-	}
-	constructor(context) {
-		this.context = context;
-	}
-	async add(input) {
-		if (input.id && this.entries.has(input.id)) {
-			await this.update(input.id, input);
-			return this._createHandle(input.id);
-		}
-		const entry = {
-			...input,
-			id: input.id ?? nanoid(),
-			timestamp: input.timestamp ?? Date.now(),
-			from: input.from ?? "server"
-		};
-		if (this.entries.size >= MAX_ENTRIES) {
-			const oldest = this.entries.keys().next().value;
-			await this.remove(oldest);
-		}
-		this.entries.set(entry.id, entry);
-		this.lastModified.set(entry.id, this._tick());
-		this.events.emit("message:added", entry);
-		if (entry.autoDelete) this._autoDeleteTimers.set(entry.id, setTimeout(() => {
-			this.remove(entry.id);
-		}, entry.autoDelete));
-		return this._createHandle(entry.id);
-	}
-	async update(id, patch) {
-		const existing = this.entries.get(id);
-		if (!existing) return void 0;
-		const updated = {
-			...existing,
-			...patch,
-			id: existing.id,
-			from: existing.from,
-			timestamp: existing.timestamp
-		};
-		this.entries.set(id, updated);
-		this.lastModified.set(id, this._tick());
-		this.events.emit("message:updated", updated);
-		if (patch.autoDelete !== void 0) {
-			const timer = this._autoDeleteTimers.get(id);
-			if (timer) {
-				clearTimeout(timer);
-				this._autoDeleteTimers.delete(id);
-			}
-			if (patch.autoDelete) this._autoDeleteTimers.set(id, setTimeout(() => {
-				this.remove(id);
-			}, patch.autoDelete));
-		}
-		return updated;
-	}
-	async remove(id) {
-		const timer = this._autoDeleteTimers.get(id);
-		if (timer) {
-			clearTimeout(timer);
-			this._autoDeleteTimers.delete(id);
-		}
-		this.entries.delete(id);
-		this.lastModified.delete(id);
-		this._recordRemoval(id, this._tick());
-		this.events.emit("message:removed", id);
-	}
-	info(message, extra) {
-		return this.add({
-			...extra,
-			message,
-			level: "info"
-		});
-	}
-	warn(message, extra) {
-		return this.add({
-			...extra,
-			message,
-			level: "warn"
-		});
-	}
-	error(message, extra) {
-		return this.add({
-			...extra,
-			message,
-			level: "error"
-		});
-	}
-	success(message, extra) {
-		return this.add({
-			...extra,
-			message,
-			level: "success"
-		});
-	}
-	debug(message, extra) {
-		return this.add({
-			...extra,
-			message,
-			level: "debug"
-		});
-	}
-	async clear() {
-		for (const timer of this._autoDeleteTimers.values()) clearTimeout(timer);
-		this._autoDeleteTimers.clear();
-		const tick = this._tick();
-		for (const id of this.entries.keys()) this._recordRemoval(id, tick);
-		this.entries.clear();
-		this.lastModified.clear();
-		this.events.emit("message:cleared");
-	}
-	listSince(since) {
-		const version = this._clock;
-		if (since == null || since < this._removalsTrimmedAt || since > version) return {
-			entries: Array.from(this.entries.values()),
-			removedIds: [],
-			version,
-			full: true
-		};
-		const entries = [];
-		for (const [id, entry] of this.entries) {
-			const mod = this.lastModified.get(id);
-			if (mod != null && mod > since) entries.push(entry);
-		}
-		const removedIds = [];
-		for (const removal of this.removals) if (removal.time > since) removedIds.push(removal.id);
-		return {
-			entries,
-			removedIds,
-			version,
-			full: false
-		};
-	}
-	_createHandle(id) {
-		const host = this;
-		return {
-			get entry() {
-				return host.entries.get(id);
-			},
-			get id() {
-				return id;
-			},
-			update: (patch) => host.update(id, patch),
-			dismiss: () => host.remove(id)
-		};
-	}
-};
-//#endregion
-//#region src/node/host-terminals.ts
-/**
-* Channel name used for terminal stream output. Stable, well-known so
-* hub-aware clients can subscribe by name.
-*/
-const TERMINAL_STREAM_CHANNEL = "devframe:terminals";
-const TERMINAL_REPLAY_WINDOW = 1e3;
-/** Max chunks retained in the per-session scrollback buffer (bounded like the replay window). */
-const TERMINAL_BUFFER_LIMIT = 1e3;
-/** TERM handed to spawned PTYs; also used to reject fallback process labels. */
-const PTY_TERM_NAME = "xterm-256color";
-var DevframeTerminalsHost = class {
-	context;
-	sessions = /* @__PURE__ */ new Map();
-	events = createEventEmitter();
-	_boundStreams = /* @__PURE__ */ new Map();
-	_channel;
-	constructor(context) {
-		this.context = context;
-	}
-	/**
-	* Lazily acquire the streaming channel — `context.rpc` isn't assigned
-	* until after every host is constructed, so we can't grab it in the
-	* constructor.
-	*/
-	getStreamingChannel() {
-		if (this._channel) return this._channel;
-		if (!this.context.rpc?.streaming) return void 0;
-		this._channel = this.context.rpc.streaming.create(TERMINAL_STREAM_CHANNEL, { replayWindow: TERMINAL_REPLAY_WINDOW });
-		return this._channel;
-	}
-	register(session) {
-		if (this.sessions.has(session.id)) throw diagnostics.DF8200({ id: session.id });
-		this.sessions.set(session.id, session);
-		this.bindStream(session);
-		this.events.emit("terminal:session:updated", session);
-		return session;
-	}
-	update(patch) {
-		if (!this.sessions.has(patch.id)) throw diagnostics.DF8201({ id: patch.id });
-		const session = this.sessions.get(patch.id);
-		Object.assign(session, patch);
-		this.sessions.set(patch.id, session);
-		this.bindStream(session);
-		this.events.emit("terminal:session:updated", session);
-	}
-	remove(session) {
-		this._boundStreams.get(session.id)?.dispose();
-		this.sessions.delete(session.id);
-		this.events.emit("terminal:session:updated", session);
-		this._boundStreams.delete(session.id);
-	}
-	bindStream(session) {
-		if (this._boundStreams.has(session.id) && this._boundStreams.get(session.id)?.stream === session.stream) return;
-		this._boundStreams.get(session.id)?.dispose();
-		this._boundStreams.delete(session.id);
-		if (!session.stream) return;
-		session.buffer ||= [];
-		const sessionBuffer = session.buffer;
-		const sink = this.getStreamingChannel()?.start({ id: session.id });
-		const reader = session.stream.getReader();
-		let disposed = false;
-		(async () => {
-			try {
-				while (true) {
-					if (disposed) break;
-					const result = await reader.read();
-					if (disposed) break;
-					if (result.done) break;
-					sessionBuffer.push(result.value);
-					if (sessionBuffer.length > TERMINAL_BUFFER_LIMIT) sessionBuffer.splice(0, sessionBuffer.length - TERMINAL_BUFFER_LIMIT);
-					sink?.write(result.value);
-				}
-				if (!disposed && sink && !sink.closed) sink.close();
-			} catch (error) {
-				if (!disposed && sink && !sink.closed) sink.error(error);
-			} finally {
-				try {
-					reader.releaseLock();
-				} catch {}
-			}
-		})();
-		this._boundStreams.set(session.id, {
-			dispose: () => {
-				disposed = true;
-				reader.cancel("terminal stream disposed").catch(() => {});
-				if (sink && !sink.closed) sink.close();
-			},
-			stream: session.stream
-		});
-	}
-	async startChildProcess(executeOptions, terminal) {
-		if (this.sessions.has(terminal.id)) throw diagnostics.DF8200({ id: terminal.id });
-		const { exec } = await import("tinyexec");
-		let controller;
-		let cp;
-		let currentResult;
-		let runId = 0;
-		let streamClosed = false;
-		let session;
-		const markStatus = (next) => {
-			if (session.status === next) return;
-			session.status = next;
-			this.events.emit("terminal:session:updated", session);
-		};
-		const closeStream = () => {
-			if (streamClosed) return;
-			streamClosed = true;
-			try {
-				controller?.close();
-			} catch {}
-		};
-		const errorStream = (error) => {
-			if (streamClosed) return;
-			streamClosed = true;
-			try {
-				controller?.error(error);
-			} catch {}
-		};
-		const stream = new ReadableStream({
-			start(_controller) {
-				controller = _controller;
-			},
-			cancel() {
-				cp?.kill();
-				cp = void 0;
-				closeStream();
-			}
-		});
-		function createChildProcess() {
-			const currentRun = ++runId;
-			let runErrored = false;
-			const cp = exec(executeOptions.command, executeOptions.args || [], { nodeOptions: {
-				env: {
-					COLORS: "true",
-					FORCE_COLOR: "true",
-					...executeOptions.env || {}
-				},
-				cwd: executeOptions.cwd ?? process$1.cwd(),
-				stdio: "pipe"
-			} });
-			const stdoutChunks = [];
-			const stderrChunks = [];
-			let settled = false;
-			let resolveOutput;
-			const outputPromise = new Promise((resolve) => {
-				resolveOutput = resolve;
-			});
-			const settle = (exitCode) => {
-				if (settled || currentRun !== runId) return;
-				settled = true;
-				resolveOutput({
-					stdout: stdoutChunks.join(""),
-					stderr: stderrChunks.join(""),
-					exitCode
-				});
-			};
-			cp.process?.stdout?.on("data", (chunk) => {
-				if (currentRun !== runId) return;
-				const text = chunk.toString();
-				stdoutChunks.push(text);
-				if (!streamClosed) controller?.enqueue(text);
-			});
-			cp.process?.stderr?.on("data", (chunk) => {
-				if (currentRun !== runId) return;
-				const text = chunk.toString();
-				stderrChunks.push(text);
-				if (!streamClosed) controller?.enqueue(text);
-			});
-			cp.process?.once("error", (error) => {
-				if (currentRun !== runId) return;
-				runErrored = true;
-				settle(cp.process?.exitCode ?? void 0);
-				errorStream(error);
-				markStatus("error");
-			});
-			cp.process?.once("close", (code) => {
-				settle(code ?? void 0);
-				if (currentRun !== runId) return;
-				closeStream();
-				if (!runErrored) markStatus(typeof code === "number" && code !== 0 ? "error" : "stopped");
-			});
-			currentResult = {
-				get pid() {
-					return cp.process?.pid;
-				},
-				get exitCode() {
-					return cp.process?.exitCode ?? void 0;
-				},
-				get killed() {
-					return cp.process?.killed === true;
-				},
-				kill: (signal) => cp.kill(signal),
-				then: (onfulfilled, onrejected) => outputPromise.then(onfulfilled, onrejected)
-			};
-			return cp;
-		}
-		cp = createChildProcess();
-		const restart = async () => {
-			if (streamClosed) throw diagnostics.DF8206({ id: terminal.id });
-			cp?.kill();
-			cp = createChildProcess();
-			markStatus("running");
-		};
-		const terminate = async () => {
-			cp?.kill();
-			cp = void 0;
-			closeStream();
-			markStatus("stopped");
-		};
-		session = {
-			...terminal,
-			status: "running",
-			stream,
-			type: "child-process",
-			executeOptions,
-			getChildProcess: () => cp?.process,
-			getResult: () => currentResult,
-			terminate,
-			restart
-		};
-		this.register(session);
-		return Promise.resolve(session);
-	}
-	async startPtySession(executeOptions, terminal) {
-		if (this.sessions.has(terminal.id)) throw diagnostics.DF8200({ id: terminal.id });
-		const { spawn } = await import("zigpty");
-		const cols = executeOptions.cols ?? 80;
-		const rows = executeOptions.rows ?? 24;
-		let controller;
-		let pty;
-		let runId = 0;
-		let streamClosed = false;
-		let session;
-		const markStatus = (next) => {
-			if (session.status === next) return;
-			session.status = next;
-			this.events.emit("terminal:session:updated", session);
-		};
-		const closeStream = () => {
-			if (streamClosed) return;
-			streamClosed = true;
-			try {
-				controller?.close();
-			} catch {}
-		};
-		const errorStream = (error) => {
-			if (streamClosed) return;
-			streamClosed = true;
-			try {
-				controller?.error(error);
-			} catch {}
-		};
-		const stream = new ReadableStream({
-			start(_controller) {
-				controller = _controller;
-			},
-			cancel() {
-				pty?.kill();
-				pty = void 0;
-				closeStream();
-			}
-		});
-		const spawnPty = () => {
-			const currentRun = ++runId;
-			const proc = spawn(executeOptions.command, executeOptions.args ?? [], {
-				name: PTY_TERM_NAME,
-				cols,
-				rows,
-				cwd: executeOptions.cwd ?? process$1.cwd(),
-				env: {
-					...process$1.env,
-					TERM: PTY_TERM_NAME,
-					COLORTERM: "truecolor",
-					FORCE_COLOR: "1",
-					...executeOptions.env ?? {}
-				}
-			});
-			proc.onData((data) => {
-				if (streamClosed || currentRun !== runId) return;
-				controller?.enqueue(typeof data === "string" ? data : data.toString("utf8"));
-			});
-			proc.onExit(({ exitCode, signal }) => {
-				if (currentRun !== runId) return;
-				closeStream();
-				markStatus(signal === 0 && exitCode !== 0 ? "error" : "stopped");
-			});
-			return proc;
-		};
-		try {
-			pty = spawnPty();
-		} catch (error) {
-			errorStream(error);
-			throw diagnostics.DF8203({
-				command: executeOptions.command,
-				reason: error instanceof Error ? error.message : String(error)
-			});
-		}
-		session = {
-			...terminal,
-			status: "running",
-			interactive: true,
-			stream,
-			type: "pty",
-			executeOptions,
-			write: (data) => {
-				try {
-					pty?.write(data);
-				} catch {}
-			},
-			resize: (nextCols, nextRows) => {
-				try {
-					pty?.resize(Math.max(1, nextCols), Math.max(1, nextRows));
-				} catch {}
-			},
-			getProcessName: () => {
-				try {
-					const name = pty?.process;
-					return name && name !== PTY_TERM_NAME ? name : void 0;
-				} catch {
-					return;
-				}
-			},
-			terminate: async () => {
-				pty?.kill();
-				pty = void 0;
-				closeStream();
-				markStatus("stopped");
-			},
-			restart: async () => {
-				if (streamClosed) throw diagnostics.DF8206({ id: terminal.id });
-				pty?.kill();
-				pty = spawnPty();
-				markStatus("running");
-			}
-		};
-		this.register(session);
-		return session;
-	}
-};
-//#endregion
-//#region src/node/rpc-builtins.ts
-/**
-* Resolve an interactive (PTY) terminal session by id, or throw. Sessions
-* spawned via `startChildProcess` are output-only and are rejected here.
-*/
-function resolveInteractiveSession(sessions, id) {
-	const session = sessions.get(id);
-	if (!session) throw diagnostics.DF8201({ id });
-	if (typeof session.write !== "function") throw diagnostics.DF8202({ id });
-	return session;
-}
-/**
-* Resolve a session that can be terminated/restarted (spawned via
-* `startChildProcess` or `startPtySession`), or throw. Sessions added with a
-* bare `register()` carry no lifecycle handle and are rejected.
-*/
-function resolveControllableSession(sessions, id) {
-	const session = sessions.get(id);
-	if (!session) throw diagnostics.DF8201({ id });
-	if (typeof session.terminate !== "function") throw diagnostics.DF8204({ id });
-	return session;
-}
-/**
-* `hub:commands:execute` — Invoke a registered server command by id. The
-* arguments after `id` are forwarded to the command's `handler(...)`.
-* Returns whatever the handler returns.
-*
-* Pairs with the `devframe:commands` shared state: clients read the list
-* from the shared state and dispatch by id via this RPC.
-*/
-const hubCommandsExecute = defineHubRpcFunction({
-	name: "hub:commands:execute",
-	type: "action",
-	setup: (context) => ({ async handler(id, ...args) {
-		return context.commands.execute(id, ...args);
-	} })
-});
-/**
-* `hub:messages:add` — Add a message from a browser client into the hub's
-* messages subsystem. Marked `from: 'browser'`. Returns the serializable
-* entry (the mutation handle stays server-side).
-*
-* Pairs with the client-side {@link import('../client').createDevframeClientHost}
-* context, whose `messages` client dispatches through these built-ins so a
-* dock client script can report into the same feed the server writes to.
-*/
-const hubMessagesAdd = defineHubRpcFunction({
-	name: "hub:messages:add",
-	type: "action",
-	jsonSerializable: true,
-	setup: (context) => ({ async handler(input) {
-		return (await context.messages.add({
-			...input,
-			from: "browser"
-		})).entry;
-	} })
-});
-/** `hub:messages:update` — Patch a message by id; returns the updated entry (or `undefined`). */
-const hubMessagesUpdate = defineHubRpcFunction({
-	name: "hub:messages:update",
-	type: "action",
-	jsonSerializable: true,
-	setup: (context) => ({ async handler(id, patch) {
-		return context.messages.update(id, patch);
-	} })
-});
-/** `hub:messages:remove` — Remove a message by id. */
-const hubMessagesRemove = defineHubRpcFunction({
-	name: "hub:messages:remove",
-	type: "action",
-	setup: (context) => ({ async handler(id) {
-		await context.messages.remove(id);
-	} })
-});
-/** `hub:messages:clear` — Remove every message. */
-const hubMessagesClear = defineHubRpcFunction({
-	name: "hub:messages:clear",
-	type: "action",
-	setup: (context) => ({ async handler() {
-		await context.messages.clear();
-	} })
-});
-/**
-* `hub:terminals:write` — Send input to an interactive PTY session spawned
-* via `ctx.terminals.startPtySession`. Lets a hub-aware terminal UI (e.g. the
-* terminals plugin) drive a session owned by another plugin.
-*/
-const hubTerminalsWrite = defineHubRpcFunction({
-	name: "hub:terminals:write",
-	type: "action",
-	setup: (context) => ({ async handler(id, data) {
-		resolveInteractiveSession(context.terminals.sessions, id).write(data);
-	} })
-});
-/** `hub:terminals:resize` — Resize an interactive PTY session by id. */
-const hubTerminalsResize = defineHubRpcFunction({
-	name: "hub:terminals:resize",
-	type: "action",
-	setup: (context) => ({ async handler(id, cols, rows) {
-		resolveInteractiveSession(context.terminals.sessions, id).resize(cols, rows);
-	} })
-});
-/**
-* `hub:terminals:terminate` — Kill a session's process while keeping the
-* session registered (its output/scrollback stays). Works for both read-only
-* child-process and interactive PTY sessions, letting a hub-aware terminal UI
-* force-kill a session owned by another plugin.
-*/
-const hubTerminalsTerminate = defineHubRpcFunction({
-	name: "hub:terminals:terminate",
-	type: "action",
-	setup: (context) => ({ async handler(id) {
-		await resolveControllableSession(context.terminals.sessions, id).terminate();
-	} })
-});
-/**
-* `hub:terminals:restart` — Re-run a session's command in place. Rejected for
-* sessions registered with `restartable: false`, whose lifecycle is owned
-* elsewhere.
-*/
-const hubTerminalsRestart = defineHubRpcFunction({
-	name: "hub:terminals:restart",
-	type: "action",
-	setup: (context) => ({ async handler(id) {
-		const session = resolveControllableSession(context.terminals.sessions, id);
-		if (session.restartable === false) throw diagnostics.DF8205({ id });
-		await session.restart();
-	} })
-});
-/**
-* `hub:terminals:remove` — Kill a session's process (when it still owns one)
-* and drop it from the registry, disposing its output stream. Lets a hub-aware
-* terminal UI discard a stopped aggregated session.
-*/
-const hubTerminalsRemove = defineHubRpcFunction({
-	name: "hub:terminals:remove",
-	type: "action",
-	setup: (context) => ({ async handler(id) {
-		const session = context.terminals.sessions.get(id);
-		if (!session) throw diagnostics.DF8201({ id });
-		const controllable = session;
-		if (typeof controllable.terminate === "function") await controllable.terminate();
-		context.terminals.remove(session);
-	} })
-});
-/**
-* `hub:docks:activate` — Ask the active viewer to switch its focused dock to
-* `dockId`, optionally carrying `params` for the target dock to interpret
-* (e.g. `{ sessionId }` for the terminals dock to focus a session).
-*
-* Any connected client may call it, which is the point: a mounted devframe
-* running in its own iframe (on its own RPC client) can steer the host shell's
-* dock selection — client-local state it otherwise can't reach. The hub
-* broadcasts the request live to connected clients (the host shell switches)
-* and mirrors it into the `devframe:docks:active` shared state (a dock that
-* mounts in response still converges on it).
-*/
-const hubDocksActivate = defineHubRpcFunction({
-	name: "hub:docks:activate",
-	type: "action",
-	setup: (context) => ({ async handler(input) {
-		context.docks.activate(input.dockId, input.params);
-	} })
-});
-/**
-* Framework-neutral RPC declarations auto-registered by
-* {@link createHubContext}. Provide additional RPCs by passing your own
-* array via `CreateHubContextOptions.builtinRpcDeclarations`; the hub's
-* list is prepended automatically.
-*/
-const builtinHubRpcDeclarations = [
-	hubCommandsExecute,
-	hubDocksActivate,
-	hubMessagesAdd,
-	hubMessagesUpdate,
-	hubMessagesRemove,
-	hubMessagesClear,
-	hubTerminalsWrite,
-	hubTerminalsResize,
-	hubTerminalsTerminate,
-	hubTerminalsRestart,
-	hubTerminalsRemove
-];
-//#endregion
-//#region src/node/context.ts
-/**
-* Create a hub-level node context: wraps devframe's `createHostContext`,
-* attaches the hub hosts (`docks`, `terminals`, `messages`, `commands`),
-* registers the hub's built-in RPC commands, and wires the shared-state
-* synchronization that powers a hub-aware client UI.
-*/
-async function createHubContext(options) {
-	const context = await createHostContext({
-		...options,
-		builtinRpcDeclarations: [...builtinHubRpcDeclarations, ...options.builtinRpcDeclarations ?? []]
-	});
-	const docks = new DevframeDocksHost(context);
-	const terminals = new DevframeTerminalsHost(context);
-	const messages = new DevframeMessagesHost(context);
-	const commands = new DevframeCommandsHost(context);
-	context.docks = docks;
-	context.terminals = terminals;
-	context.messages = messages;
-	context.commands = commands;
-	await docks.init();
-	let jsonRenderCounter = 0;
-	context.createJsonRenderer = (initialSpec) => {
-		const stateKey = `devframe:json-render:${jsonRenderCounter++}`;
-		const statePromise = context.rpc.sharedState.get(stateKey, { initialValue: initialSpec });
-		return {
-			_stateKey: stateKey,
-			async updateSpec(spec) {
-				(await statePromise).mutate(() => spec);
-			},
-			async updateState(newState) {
-				(await statePromise).mutate((draft) => {
-					draft.state = {
-						...draft.state,
-						...newState
-					};
-				});
-			}
-		};
-	};
-	const debounceMs = options.mode === "build" ? 0 : 10;
-	const docksSharedState = await context.rpc.sharedState.get("devframe:docks", { initialValue: [] });
-	const refreshDocks = debounce(() => {
-		docksSharedState.mutate(() => docks.values());
-	}, debounceMs);
-	docks.events.on("dock:entry:updated", refreshDocks);
-	docksSharedState.mutate(() => docks.values());
-	const activeDockSharedState = await context.rpc.sharedState.get("devframe:docks:active", { initialValue: { activation: null } });
-	docks.events.on("dock:activate", (activation) => {
-		activeDockSharedState.mutate((state) => {
-			state.activation = activation;
-		});
-		context.rpc.broadcast({
-			method: "devframe:docks:activate",
-			args: [activation]
-		});
-	});
-	const broadcastTerminals = debounce(() => {
-		context.rpc.broadcast({
-			method: "devframe:terminals:updated",
-			args: []
-		});
-		docksSharedState.mutate(() => docks.values());
-	}, debounceMs);
-	terminals.events.on("terminal:session:updated", broadcastTerminals);
-	const broadcastMessages = debounce(() => {
-		context.rpc.broadcast({
-			method: "devframe:messages:updated",
-			args: []
-		});
-		docksSharedState.mutate(() => docks.values());
-	}, debounceMs);
-	messages.events.on("message:added", broadcastMessages);
-	messages.events.on("message:updated", broadcastMessages);
-	messages.events.on("message:removed", broadcastMessages);
-	messages.events.on("message:cleared", broadcastMessages);
-	const commandsSharedState = await context.rpc.sharedState.get("devframe:commands", { initialValue: [] });
-	const syncCommands = debounce(() => {
-		commandsSharedState.mutate(() => commands.list());
-	}, debounceMs);
-	commands.events.on("command:registered", syncCommands);
-	commands.events.on("command:unregistered", syncCommands);
-	commandsSharedState.mutate(() => commands.list());
-	return context;
-}
-//#endregion
-//#region src/node/mount-devframe.ts
-/**
-* Find the next free dock id derived from `baseId`. Returns `baseId`
-* when it is unused, otherwise appends `-2`, `-3`, … until a free slot
-* is found. Used by the `'duplicate'` strategy so co-existing instances
-* never collide in the dock registry.
-*/
-function nextAvailableDockId(views, baseId) {
-	if (!views.has(baseId)) return baseId;
-	let n = 2;
-	while (views.has(`${baseId}-${n}`)) n++;
-	return `${baseId}-${n}`;
-}
-/**
-* Framework-neutral primitive — mounts a {@link DevframeDefinition} as a
-* dock inside a hub-aware context: serves the devframe's SPA at the
-* resolved base path, synthesizes an iframe dock entry from the
-* definition's metadata, and runs the definition's `setup(ctx)`.
-*
-* Framework kits wrap this with their own plugin/middleware machinery —
-* e.g. `@vitejs/devtools-kit`'s `createPluginFromDevframe` returns a
-* Vite `Plugin` whose `devtools.setup` ultimately delegates here.
-*/
-async function mountDevframe(ctx, d, options = {}) {
-	const strategy = d.duplicationStrategy ?? "warn";
-	const isDuplicate = ctx.docks.views.has(d.id);
-	if (isDuplicate && strategy !== "duplicate") {
-		if (strategy === "throw") throw diagnostics.DF8105({
-			id: d.id,
-			name: d.name
-		});
-		if (strategy === "warn") diagnostics.DF8105({
-			id: d.id,
-			name: d.name
-		});
-		return;
-	}
-	const id = isDuplicate ? nextAvailableDockId(ctx.docks.views, d.id) : d.id;
-	const base = options.base ?? (id === d.id ? resolveBasePath(d, "hosted") : resolveBasePath({
-		...d,
-		id,
-		basePath: void 0
-	}, "hosted"));
-	if (d.cli?.distDir) {
-		ctx.views.hostStatic(base, resolve(d.cli.distDir));
-		if (ctx.host.mountConnectionMeta) await ctx.host.mountConnectionMeta(base);
-		else diagnostics.DF8106({
-			id,
-			name: d.name,
-			base
-		});
-	}
-	ctx.docks.register({
-		id,
-		title: d.name,
-		icon: d.icon ?? "ph:plug-duotone",
-		...d.dock,
-		...options.dock,
-		type: "iframe",
-		url: base
-	});
-	await d.setup(ctx);
-}
-//#endregion
 //#region ../../node_modules/.pnpm/acorn@8.16.0/node_modules/acorn/dist/acorn.mjs
 var astralIdentifierCodes = [
 	509,
@@ -6639,4 +5468,4 @@ function createSimpleClientScript(fn) {
 	};
 }
 //#endregion
-export { DEFAULT_CATEGORIES_ORDER, DevframeCommandsHost, DevframeDocksHost, DevframeMessagesHost, DevframeTerminalsHost, builtinHubRpcDeclarations, createHubContext, createSimpleClientScript, hubCommandsExecute, hubDocksActivate, hubMessagesAdd, hubMessagesClear, hubMessagesRemove, hubMessagesUpdate, hubTerminalsRemove, hubTerminalsResize, hubTerminalsRestart, hubTerminalsTerminate, hubTerminalsWrite, mountDevframe };
+export { DevframeCommandsHost, DevframeDocksHost, DevframeMessagesHost, DevframeTerminalsHost, builtinHubRpcDeclarations, createHubContext, createSimpleClientScript, hubCommandsExecute, hubDocksActivate, hubMessagesAdd, hubMessagesClear, hubMessagesRemove, hubMessagesUpdate, hubTerminalsRemove, hubTerminalsResize, hubTerminalsRestart, hubTerminalsTerminate, hubTerminalsWrite };