@devframes/hub 0.5.4 → 0.6.0-beta.2

package/dist/node/index.mjs

@@ -1,9 +1,9 @@
-import { r as defineHubRpcFunction } from "../define-tHP6fX6A.mjs";
+import { r as defineHubRpcFunction } from "../define-Dp-x6d09.mjs";
 import { DEFAULT_STATE_USER_SETTINGS } from "../constants.mjs";
 import { REMOTE_CONNECTION_KEY } from "devframe/constants";
+import { createEventEmitter } from "devframe/utils/events";
 import { createHostContext, createStorage } from "devframe/node";
 import { debounce } from "perfect-debounce";
-import { createEventEmitter } from "devframe/utils/events";
 import { defineDiagnostics } from "nostics";
 import { colors } from "devframe/utils/colors";
 import { ansiFormatter } from "nostics/formatters/ansi";
@@ -33,8 +33,14 @@ const diagnostics = defineDiagnostics({
 			why: (p) => `Dock with id "${p.id}" is already registered`,
 			fix: "Use the `force` parameter to overwrite an existing registration."
 		},
-		DF8101: { why: "Cannot change the id of a dock. Use register() to add new docks." },
-		DF8102: { why: (p) => `Dock with id "${p.id}" is not registered. Use register() to add new docks.` },
+		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."
@@ -43,10 +49,19 @@ const diagnostics = defineDiagnostics({
 			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."
+		},
 		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}` },
 		DF8400: { why: (p) => `Command "${p.id}" is already registered` },
-		DF8401: { why: "Cannot change the id of a command. Use register() to add new commands." },
+		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`,
@@ -192,13 +207,15 @@ function buildRemoteUrl(baseUrl, payload, transport) {
 }
 var DevframeDocksHost = class {
 	context;
+	builtinDocks;
 	views = /* @__PURE__ */ new Map();
 	events = createEventEmitter();
 	userSettings = void 0;
 	/** Dock-id → allocated remote token + resolved options. */
 	remoteDocks = /* @__PURE__ */ new Map();
-	constructor(context) {
+	constructor(context, builtinDocks = {}) {
 		this.context = context;
+		this.builtinDocks = builtinDocks;
 	}
 	async init() {
 		this.userSettings = await this.context.rpc.sharedState.get("devframe:user-settings", { sharedState: createStorage({
@@ -208,36 +225,36 @@ var DevframeDocksHost = class {
 	}
 	values({ includeBuiltin = true } = {}) {
 		const context = this.context;
-		const builtinDocksEntries = [
-			{
-				type: "~builtin",
-				id: "~terminals",
-				title: "Terminals",
-				icon: "ph:terminal-duotone",
-				category: "~builtin",
-				get when() {
-					return context.terminals.sessions.size === 0 ? "false" : void 0;
-				}
-			},
-			{
-				type: "~builtin",
-				id: "~messages",
-				title: "Messages & Notifications",
-				icon: "ph:notification-duotone",
-				category: "~builtin",
-				get badge() {
-					const size = context.messages.entries.size;
-					return size > 0 ? String(size) : void 0;
-				}
-			},
-			{
-				type: "~builtin",
-				id: "~settings",
-				title: "Settings",
-				category: "~builtin",
-				icon: "ph:gear-duotone"
+		const { terminals = true, messages = true, settings = true } = this.builtinDocks;
+		const builtinDocksEntries = [];
+		if (terminals) builtinDocksEntries.push({
+			type: "~builtin",
+			id: "~terminals",
+			title: "Terminals",
+			icon: "ph:terminal-duotone",
+			category: "~builtin",
+			get when() {
+				return context.terminals.sessions.size === 0 ? "false" : void 0;
+			}
+		});
+		if (messages) builtinDocksEntries.push({
+			type: "~builtin",
+			id: "~messages",
+			title: "Messages & Notifications",
+			icon: "ph:notification-duotone",
+			category: "~builtin",
+			get badge() {
+				const size = context.messages.entries.size;
+				return size > 0 ? String(size) : void 0;
 			}
-		];
+		});
+		if (settings) builtinDocksEntries.push({
+			type: "~builtin",
+			id: "~settings",
+			title: "Settings",
+			category: "~builtin",
+			icon: "ph:gear-duotone"
+		});
 		return [...Array.from(this.views.values(), (view) => this.projectView(view)), ...includeBuiltin ? builtinDocksEntries : []];
 	}
 	projectView(view) {
@@ -267,7 +284,10 @@ var DevframeDocksHost = class {
 		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();
+			if (patch.id && patch.id !== view.id) throw diagnostics.DF8101({
+				id: view.id,
+				attempted: patch.id
+			});
 			this.update(Object.assign(this.views.get(view.id), patch));
 		} };
 	}
@@ -306,13 +326,6 @@ var DevframeDocksHost = class {
 //#region src/node/host-messages.ts
 const MAX_ENTRIES = 1e3;
 const MAX_REMOVALS = 1e3;
-function recordRemoval(removals, id, time) {
-	removals.push({
-		id,
-		time
-	});
-	if (removals.length > MAX_REMOVALS) removals.splice(0, removals.length - MAX_REMOVALS);
-}
 var DevframeMessagesHost = class {
 	context;
 	entries = /* @__PURE__ */ new Map();
@@ -323,9 +336,25 @@ var DevframeMessagesHost = class {
 	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;
 	}
@@ -385,18 +414,75 @@ var DevframeMessagesHost = class {
 		}
 		this.entries.delete(id);
 		this.lastModified.delete(id);
-		recordRemoval(this.removals, id, this._tick());
+		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()) recordRemoval(this.removals, id, 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 {
@@ -419,6 +505,8 @@ var DevframeMessagesHost = class {
 */
 const TERMINAL_STREAM_CHANNEL = "devframe:terminals";
 const TERMINAL_REPLAY_WINDOW = 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();
@@ -576,10 +664,123 @@ var DevframeTerminalsHost = class {
 		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;
+		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: {
+					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(() => {
+				if (currentRun === runId) closeStream();
+			});
+			return proc;
+		};
+		try {
+			pty = spawnPty();
+		} catch (error) {
+			errorStream(error);
+			throw diagnostics.DF8203({
+				command: executeOptions.command,
+				reason: error instanceof Error ? error.message : String(error)
+			});
+		}
+		const 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();
+			},
+			restart: async () => {
+				pty?.kill();
+				pty = spawnPty();
+			}
+		};
+		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;
+}
+/**
 * `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.
@@ -595,12 +796,85 @@ const hubCommandsExecute = defineHubRpcFunction({
 	} })
 });
 /**
+* `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);
+	} })
+});
+/**
 * 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];
+const builtinHubRpcDeclarations = [
+	hubCommandsExecute,
+	hubMessagesAdd,
+	hubMessagesUpdate,
+	hubMessagesRemove,
+	hubMessagesClear,
+	hubTerminalsWrite,
+	hubTerminalsResize
+];
 //#endregion
 //#region src/node/context.ts
 /**
@@ -614,7 +888,7 @@ async function createHubContext(options) {
 		...options,
 		builtinRpcDeclarations: [...builtinHubRpcDeclarations, ...options.builtinRpcDeclarations ?? []]
 	});
-	const docks = new DevframeDocksHost(context);
+	const docks = new DevframeDocksHost(context, options.builtinDocks);
 	const terminals = new DevframeTerminalsHost(context);
 	const messages = new DevframeMessagesHost(context);
 	const commands = new DevframeCommandsHost(context);
@@ -680,6 +954,18 @@ async function createHubContext(options) {
 //#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
@@ -690,10 +976,31 @@ async function createHubContext(options) {
 * Vite `Plugin` whose `devtools.setup` ultimately delegates here.
 */
 async function mountDevframe(ctx, d, options = {}) {
-	const base = options.base ?? resolveBasePath(d, "hosted");
-	if (d.cli?.distDir) ctx.views.hostStatic(base, resolve(d.cli.distDir));
+	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));
+		await ctx.host.mountConnectionMeta?.(base);
+	}
 	ctx.docks.register({
-		id: d.id,
+		id,
 		title: d.name,
 		icon: d.icon ?? "ph:plug-duotone",
 		...options.dock,
@@ -6142,4 +6449,4 @@ function createSimpleClientScript(fn) {
 	};
 }
 //#endregion
-export { DevframeCommandsHost, DevframeDocksHost, DevframeMessagesHost, DevframeTerminalsHost, builtinHubRpcDeclarations, createHubContext, createSimpleClientScript, hubCommandsExecute, mountDevframe };
+export { DevframeCommandsHost, DevframeDocksHost, DevframeMessagesHost, DevframeTerminalsHost, builtinHubRpcDeclarations, createHubContext, createSimpleClientScript, hubCommandsExecute, hubMessagesAdd, hubMessagesClear, hubMessagesRemove, hubMessagesUpdate, hubTerminalsResize, hubTerminalsWrite, mountDevframe };