@jhebe/web-terminal 0.2.0

package/dist/web-terminal.js

@@ -0,0 +1,352 @@
+import { FitAddon as e } from "@xterm/addon-fit";
+import { Terminal as t } from "@xterm/xterm";
+//#region src/protocol.ts
+function n(e) {
+	let t = r(e);
+	if (!(!t || typeof t.type != "string")) switch (t.type) {
+		case "sessions": return Array.isArray(t.sessions) && t.sessions.every(i) ? {
+			type: "sessions",
+			sessions: t.sessions
+		} : void 0;
+		case "opened": return a(t) && i(t.session) ? {
+			type: "opened",
+			requestId: t.requestId,
+			session: t.session
+		} : void 0;
+		case "closed":
+		case "written":
+		case "unobserved": return a(t) && typeof t.sessionId == "string" ? {
+			type: t.type,
+			requestId: t.requestId,
+			sessionId: t.sessionId
+		} : void 0;
+		case "observing": return a(t) && i(t.session) && typeof t.history == "string" ? {
+			type: "observing",
+			requestId: t.requestId,
+			session: t.session,
+			history: t.history
+		} : void 0;
+		case "attached": return a(t) && i(t.session) && typeof t.history == "string" ? {
+			type: "attached",
+			requestId: t.requestId,
+			session: t.session,
+			history: t.history
+		} : void 0;
+		case "detached": return a(t) && typeof t.sessionId == "string" ? {
+			type: "detached",
+			requestId: t.requestId,
+			sessionId: t.sessionId
+		} : void 0;
+		case "output": return typeof t.sessionId == "string" && typeof t.data == "string" ? {
+			type: "output",
+			sessionId: t.sessionId,
+			data: t.data
+		} : void 0;
+		case "exit": return typeof t.sessionId == "string" && typeof t.exitCode == "number" && (t.signal === void 0 || typeof t.signal == "number") ? {
+			type: "exit",
+			sessionId: t.sessionId,
+			exitCode: t.exitCode,
+			...t.signal === void 0 ? {} : { signal: t.signal }
+		} : void 0;
+		case "error": return typeof t.message == "string" && (t.requestId === void 0 || typeof t.requestId == "string") ? {
+			type: "error",
+			message: t.message,
+			...t.requestId === void 0 ? {} : { requestId: t.requestId }
+		} : void 0;
+		default: return;
+	}
+}
+function r(e) {
+	if (typeof e == "string") try {
+		let t = JSON.parse(e);
+		return o(t) ? t : void 0;
+	} catch {
+		return;
+	}
+}
+function i(e) {
+	return o(e) && typeof e.id == "string" && typeof e.name == "string" && (e.state === "running" || e.state === "exited") && typeof e.attached == "boolean" && typeof e.observers == "number" && typeof e.createdAt == "string" && typeof e.lastActiveAt == "string" && (e.exitCode === void 0 || typeof e.exitCode == "number");
+}
+function a(e) {
+	return typeof e.requestId == "string";
+}
+function o(e) {
+	return typeof e == "object" && !!e;
+}
+//#endregion
+//#region src/terminal-view.ts
+var s = class {
+	terminal;
+	fitAddon = new e();
+	target;
+	controller;
+	resizeObserver;
+	disposed = !1;
+	constructor(e) {
+		this.target = e.target, this.controller = e.controller, this.terminal = new t({
+			cursorBlink: !0,
+			convertEol: !0,
+			fontFamily: "\"SFMono-Regular\", Consolas, \"Liberation Mono\", Menlo, monospace",
+			fontSize: 14,
+			theme: {
+				background: "#111318",
+				foreground: "#e7e9ee",
+				cursor: "#8bd5ca",
+				selectionBackground: "#3b4252"
+			},
+			...e.terminalOptions
+		}), this.target.classList.add("web-terminal"), this.terminal.loadAddon(this.fitAddon), this.terminal.open(this.target), this.terminal.onData((e) => this.controller.input(e)), this.terminal.onResize(({ cols: e, rows: t }) => this.controller.resize(e, t)), this.resizeObserver = new ResizeObserver(() => this.fit()), this.resizeObserver.observe(this.target), this.fit();
+	}
+	write(e) {
+		this.disposed || this.terminal.write(e);
+	}
+	focus() {
+		this.assertActive(), this.terminal.focus();
+	}
+	fit() {
+		this.disposed || this.fitAddon.fit();
+	}
+	dispose() {
+		this.disposed || (this.disposeVisuals(), this.controller.release(this));
+	}
+	disposeVisuals() {
+		this.disposed || (this.disposed = !0, this.resizeObserver.disconnect(), this.terminal.dispose(), this.target.classList.remove("web-terminal"));
+	}
+	assertActive() {
+		if (this.disposed) throw Error("This terminal view has been disposed.");
+	}
+}, c = class {
+	options;
+	sessionListeners = /* @__PURE__ */ new Set();
+	eventListeners = /* @__PURE__ */ new Set();
+	pending = /* @__PURE__ */ new Map();
+	socket;
+	connectPromise;
+	sessionSnapshot = [];
+	attachedSessionId;
+	view;
+	viewSessionId;
+	bufferedOutput = [];
+	constructor(e) {
+		this.options = e, e.autoConnect !== !1 && this.connect().catch((e) => this.reportError(d(e)));
+	}
+	get sessions() {
+		return this.sessionSnapshot;
+	}
+	get connected() {
+		return this.socket?.readyState === WebSocket.OPEN;
+	}
+	get attachedSession() {
+		return this.attachedSessionId;
+	}
+	connect() {
+		return this.connected ? Promise.resolve() : (this.connectPromise ||= new Promise((e, t) => {
+			let r = typeof this.options.socketUrl == "function" ? this.options.socketUrl() : this.options.socketUrl, i = new WebSocket(r);
+			this.socket = i, i.addEventListener("open", () => {
+				this.connectPromise = void 0, this.emitEvent({ type: "connected" }), e();
+			}, { once: !0 }), i.addEventListener("message", (e) => {
+				this.handleMessage(n(e.data));
+			}), i.addEventListener("error", () => {
+				let e = /* @__PURE__ */ Error("Terminal WebSocket connection failed.");
+				this.connectPromise && (this.connectPromise = void 0, t(e)), this.reportError(e);
+			}), i.addEventListener("close", () => {
+				this.socket === i && (this.socket = void 0, this.connectPromise = void 0, this.attachedSessionId = void 0, this.rejectPending(/* @__PURE__ */ Error("Terminal connection closed before the operation completed.")), this.emitEvent({ type: "disconnected" }));
+			});
+		}), this.connectPromise);
+	}
+	disconnect() {
+		this.socket?.close(1e3, "Client disconnected");
+	}
+	async open(e = {}) {
+		let t = await this.request({
+			type: "open",
+			requestId: u(),
+			...e.name === void 0 ? {} : { name: e.name }
+		});
+		if (t.type !== "opened") throw Error("Unexpected response while opening a terminal session.");
+		return this.emitEvent({
+			type: "opened",
+			sessionId: t.session.id
+		}), t.session;
+	}
+	async close(e) {
+		if ((await this.request({
+			type: "close",
+			requestId: u(),
+			sessionId: e
+		})).type !== "closed") throw Error("Unexpected response while closing a terminal session.");
+		this.attachedSessionId === e && (this.attachedSessionId = void 0, this.disposeView()), this.emitEvent({
+			type: "closed",
+			sessionId: e
+		});
+	}
+	async write(e, t) {
+		if ((await this.request({
+			type: "write",
+			requestId: u(),
+			sessionId: e,
+			data: t
+		})).type !== "written") throw Error("Unexpected response while writing to a terminal session.");
+	}
+	async attach(e) {
+		let t = await this.request({
+			type: "attach",
+			requestId: u(),
+			sessionId: e
+		});
+		if (t.type !== "attached") throw Error("Unexpected response while attaching a terminal session.");
+		return this.attachedSessionId = e, this.bufferedOutput = [], this.emitEvent({
+			type: "attached",
+			sessionId: e
+		}), {
+			session: t.session,
+			history: t.history
+		};
+	}
+	async detach() {
+		let e = this.attachedSessionId;
+		if (!e) {
+			this.disposeView();
+			return;
+		}
+		await this.detachSession(e);
+	}
+	async detachSession(e) {
+		if ((await this.request({
+			type: "detach",
+			requestId: u(),
+			sessionId: e
+		})).type !== "detached") throw Error("Unexpected response while detaching a terminal session.");
+		this.attachedSessionId === e && (this.attachedSessionId = void 0), this.viewSessionId === e && this.disposeView(), this.emitEvent({
+			type: "detached",
+			sessionId: e
+		});
+	}
+	async display(e, t, n = {}) {
+		let r = await this.attach(e);
+		this.disposeView();
+		let i = new s({
+			target: t,
+			controller: {
+				input: (e) => this.input(e),
+				resize: (e, t) => this.resize(e, t),
+				release: (e) => this.releaseView(e)
+			},
+			...n.terminalOptions === void 0 ? {} : { terminalOptions: n.terminalOptions }
+		});
+		this.view = i, this.viewSessionId = e, i.write(r.history);
+		for (let e of this.bufferedOutput) i.write(e);
+		return this.bufferedOutput = [], i.focus(), i;
+	}
+	subscribeSessions(e) {
+		return this.sessionListeners.add(e), e(this.sessionSnapshot), () => this.sessionListeners.delete(e);
+	}
+	subscribeEvents(e) {
+		return this.eventListeners.add(e), () => this.eventListeners.delete(e);
+	}
+	dispose() {
+		this.disposeView(), this.disconnect(), this.sessionListeners.clear(), this.eventListeners.clear();
+	}
+	input(e) {
+		this.attachedSessionId && this.send({
+			type: "input",
+			sessionId: this.attachedSessionId,
+			data: e
+		});
+	}
+	resize(e, t) {
+		this.attachedSessionId && this.send({
+			type: "resize",
+			sessionId: this.attachedSessionId,
+			cols: e,
+			rows: t
+		});
+	}
+	releaseView(e) {
+		if (this.view !== e) return;
+		let t = this.viewSessionId;
+		this.view = void 0, this.viewSessionId = void 0, t && this.detachSession(t).catch((e) => this.reportError(d(e)));
+	}
+	disposeView() {
+		let e = this.view;
+		this.view = void 0, this.viewSessionId = void 0, e?.disposeVisuals();
+	}
+	async request(e) {
+		if (!("requestId" in e)) throw Error("Request messages require an identity.");
+		return await this.connect(), new Promise((t, n) => {
+			this.pending.set(e.requestId, {
+				resolve: t,
+				reject: n
+			});
+			try {
+				this.send(e);
+			} catch (t) {
+				this.pending.delete(e.requestId), n(d(t));
+			}
+		});
+	}
+	send(e) {
+		if (!this.socket || this.socket.readyState !== WebSocket.OPEN) throw Error("Terminal client is not connected.");
+		this.socket.send(JSON.stringify(e));
+	}
+	handleMessage(e) {
+		if (!e) {
+			this.reportError(/* @__PURE__ */ Error("Received an invalid terminal server message."));
+			return;
+		}
+		if (e.type === "sessions") {
+			this.sessionSnapshot = Object.freeze(e.sessions.map((e) => Object.freeze({ ...e })));
+			let t = this.attachedSessionId;
+			t && !this.sessionSnapshot.some((e) => e.id === t) && (this.attachedSessionId = void 0, this.disposeView(), this.emitEvent({
+				type: "detached",
+				sessionId: t
+			}));
+			for (let e of this.sessionListeners) e(this.sessionSnapshot);
+			return;
+		}
+		if (e.type === "output") {
+			if (e.sessionId !== this.attachedSessionId) return;
+			this.view ? this.view.write(e.data) : this.bufferedOutput.push(e.data);
+			return;
+		}
+		if (e.type === "exit") {
+			this.emitEvent({
+				type: "exit",
+				sessionId: e.sessionId,
+				exitCode: e.exitCode
+			});
+			return;
+		}
+		if (e.type === "error") {
+			let t = Error(e.message);
+			if (e.requestId) {
+				let n = this.pending.get(e.requestId);
+				this.pending.delete(e.requestId), n?.reject(t);
+			} else this.reportError(t);
+			return;
+		}
+		let t = this.pending.get(e.requestId);
+		t && (this.pending.delete(e.requestId), t.resolve(e));
+	}
+	rejectPending(e) {
+		for (let t of this.pending.values()) t.reject(e);
+		this.pending.clear();
+	}
+	emitEvent(e) {
+		for (let t of this.eventListeners) t(e);
+	}
+	reportError(e) {
+		this.options.onError ? this.options.onError(e) : console.error(e);
+	}
+};
+function l(e) {
+	return new c(e);
+}
+function u() {
+	return crypto.randomUUID();
+}
+function d(e) {
+	return e instanceof Error ? e : Error(String(e));
+}
+//#endregion
+export { c as TerminalClient, s as TerminalView, l as createTerminalClient };

package/dist-server/server/history-buffer.d.ts

@@ -0,0 +1,8 @@
+export declare class HistoryBuffer {
+    private readonly limitBytes;
+    private chunks;
+    private totalBytes;
+    constructor(limitBytes: number);
+    append(data: string): void;
+    read(): string;
+}

package/dist-server/server/history-buffer.js

@@ -0,0 +1,59 @@
+export class HistoryBuffer {
+    limitBytes;
+    chunks = [];
+    totalBytes = 0;
+    constructor(limitBytes) {
+        this.limitBytes = limitBytes;
+    }
+    append(data) {
+        if (this.limitBytes === 0 || data.length === 0) {
+            return;
+        }
+        let normalized = data;
+        let bytes = Buffer.byteLength(normalized);
+        if (bytes > this.limitBytes) {
+            normalized = trimToLastBytes(normalized, this.limitBytes);
+            bytes = Buffer.byteLength(normalized);
+            this.chunks = [];
+            this.totalBytes = 0;
+        }
+        this.chunks.push({ data: normalized, bytes });
+        this.totalBytes += bytes;
+        while (this.totalBytes > this.limitBytes &&
+            this.chunks.length > 1) {
+            const removed = this.chunks.shift();
+            if (removed) {
+                this.totalBytes -= removed.bytes;
+            }
+        }
+        const first = this.chunks[0];
+        if (first && this.totalBytes > this.limitBytes) {
+            const excess = this.totalBytes - this.limitBytes;
+            first.data = trimToLastBytes(first.data, first.bytes - excess);
+            const nextBytes = Buffer.byteLength(first.data);
+            this.totalBytes += nextBytes - first.bytes;
+            first.bytes = nextBytes;
+        }
+    }
+    read() {
+        return this.chunks.map(({ data }) => data).join('');
+    }
+}
+function trimToLastBytes(value, limitBytes) {
+    const characters = Array.from(value);
+    let bytes = 0;
+    let start = characters.length;
+    while (start > 0) {
+        const character = characters[start - 1];
+        if (character === undefined) {
+            break;
+        }
+        const characterBytes = Buffer.byteLength(character);
+        if (bytes + characterBytes > limitBytes) {
+            break;
+        }
+        bytes += characterBytes;
+        start -= 1;
+    }
+    return characters.slice(start).join('');
+}

package/dist-server/server/index.d.ts

@@ -0,0 +1,2 @@
+export { createTerminalSessionManager, type OpenSessionOptions, type SessionAttachment, type SessionEvent, type SessionObservation, type SessionSink, type TerminalSessionManager, type TerminalSessionManagerOptions, } from './session-manager.js';
+export { attachTerminalServer, type TerminalAction, type TerminalServer, type TerminalServerOptions, } from './terminal-server.js';

package/dist-server/server/index.js

@@ -0,0 +1,2 @@
+export { createTerminalSessionManager, } from './session-manager.js';
+export { attachTerminalServer, } from './terminal-server.js';

package/dist-server/server/session-manager.d.ts

@@ -0,0 +1,51 @@
+import type { SessionSummary } from '../src/protocol.js';
+export interface TerminalSessionManagerOptions {
+    shell?: string;
+    shellArgs?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    historyLimitBytes?: number;
+    idleTimeoutMs?: number;
+    maxSessions?: number;
+    maxObserversPerSession?: number;
+    maxWriteBytes?: number;
+    maxInputBytes?: number;
+}
+export interface OpenSessionOptions {
+    name?: string;
+    shell?: string;
+    shellArgs?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface SessionSink {
+    output(data: string): void;
+    exit(exitCode: number, signal?: number): void;
+}
+export interface SessionAttachment {
+    readonly session: SessionSummary;
+    readonly history: string;
+}
+export interface SessionObservation {
+    readonly session: SessionSummary;
+    readonly history: string;
+}
+export interface SessionEvent {
+    readonly type: 'opened' | 'attached' | 'detached' | 'exited' | 'closed' | 'expired';
+    readonly session: SessionSummary;
+}
+export interface TerminalSessionManager {
+    readonly sessions: readonly SessionSummary[];
+    open(options?: OpenSessionOptions): SessionSummary;
+    close(sessionId: string): void;
+    write(sessionId: string, data: string): void;
+    observe(sessionId: string, observerId: string, sink: SessionSink): SessionObservation;
+    unobserve(sessionId: string, observerId: string): void;
+    attach(sessionId: string, attachmentId: string, sink: SessionSink): SessionAttachment;
+    detach(sessionId: string, attachmentId: string): void;
+    input(sessionId: string, attachmentId: string, data: string): void;
+    resize(sessionId: string, attachmentId: string, cols: number, rows: number): void;
+    subscribe(listener: (event: SessionEvent) => void): () => void;
+    shutdown(): void;
+}
+export declare function createTerminalSessionManager(options?: TerminalSessionManagerOptions): TerminalSessionManager;