@jhebe/web-terminal 0.2.0

package/README.md

@@ -0,0 +1,86 @@
+# web-terminal
+
+`web-terminal` is a framework-agnostic terminal-session library. A hosting
+backend instantiates a private in-memory session manager; browser applications
+interact through the limited verbs `open`, `close`, `attach`, `detach`, and
+`display`.
+
+## Backend
+
+```ts
+import { createServer } from 'node:http';
+import {
+  attachTerminalServer,
+  createTerminalSessionManager,
+} from '@jhebe/web-terminal/server';
+
+const server = createServer(app);
+const manager = createTerminalSessionManager({
+  cwd: '/workspace',
+  idleTimeoutMs: 10 * 60 * 1000,
+  maxSessions: 100,
+  maxObserversPerSession: 32,
+  maxInputBytes: 64 * 1024,
+  maxWriteBytes: 64 * 1024,
+});
+
+manager.observe(sessionId, 'host-monitor', {
+  output: (data) => process.stdout.write(data),
+  exit: (code) => console.log('Exited:', code),
+});
+
+manager.write(sessionId, 'echo controlled by host\r');
+manager.unobserve(sessionId, 'host-monitor');
+
+attachTerminalServer({
+  server,
+  manager,
+  maxPayloadBytes: 64 * 1024,
+  authorize: (request, action, sessionId) => {
+    return authorizeUser(request, action, sessionId);
+  },
+});
+```
+
+The host owns authentication, permissions, names, business context, and page
+layout. The manager owns PTY lifetime, session identity, attachments, bounded
+history, and idle cleanup.
+
+## Browser
+
+```ts
+import { createTerminalClient } from '@jhebe/web-terminal';
+import '@jhebe/web-terminal/style.css';
+
+const client = createTerminalClient({
+  socketUrl: 'wss://example.com/terminal',
+});
+
+const session = await client.open({ name: '小鍵' });
+const view = await client.display(session.id, element);
+
+await client.write(session.id, 'echo inserted by the host UI\r');
+await client.detach();       // Session and process continue.
+await client.display(session.id, anotherElement);
+await client.close(session.id); // Session and process end permanently.
+```
+
+This version is intentionally in-memory and single-process. Sessions do not
+survive backend restart and are not coordinated across multiple backend
+instances.
+
+## CLI
+
+The package installs a `web-terminal` command that uses the same authenticated
+WebSocket endpoint:
+
+```bash
+web-terminal --url ws://127.0.0.1:5173/terminal sessions
+web-terminal --url ws://127.0.0.1:5173/terminal open "小鍵"
+web-terminal --url ws://127.0.0.1:5173/terminal send SESSION_ID "echo hello"
+web-terminal --url ws://127.0.0.1:5173/terminal follow SESSION_ID
+web-terminal --url ws://127.0.0.1:5173/terminal close SESSION_ID
+```
+
+Use `--token` or `WEB_TERMINAL_TOKEN` when the host authorization callback
+expects a bearer token.

package/bin/web-terminal.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+
+import { randomUUID } from 'node:crypto';
+import process from 'node:process';
+import { WebSocket } from 'ws';
+
+async function main() {
+const { command, arguments: commandArguments, url, token } = parseArguments(
+  process.argv.slice(2),
+);
+
+if (!command || command === 'help' || command === '--help') {
+  printHelp();
+  process.exit(0);
+}
+
+const client = new SessionWireClient(url, token);
+
+try {
+  await client.connect();
+
+  switch (command) {
+    case 'sessions': {
+      const sessions = await client.waitForSessions();
+      if (sessions.length === 0) {
+        console.log('No terminal sessions.');
+        break;
+      }
+      for (const session of sessions) {
+        console.log(
+          [
+            session.id,
+            session.state,
+            session.attached ? 'displayed' : 'detached',
+            `${session.observers} observer(s)`,
+            session.name,
+          ].join('\t'),
+        );
+      }
+      break;
+    }
+    case 'open': {
+      const response = await client.request({
+        type: 'open',
+        requestId: randomUUID(),
+        ...(commandArguments.length === 0
+          ? {}
+          : { name: commandArguments.join(' ') }),
+      });
+      requireResponse(response, 'opened');
+      console.log(response.session.id);
+      break;
+    }
+    case 'send':
+    case 'write': {
+      const [sessionId, ...inputParts] = commandArguments;
+      if (!sessionId || inputParts.length === 0) {
+        throw new Error(`${command} requires a session ID and input.`);
+      }
+      const data =
+        command === 'send'
+          ? `${inputParts.join(' ')}\r`
+          : inputParts.join(' ');
+      const response = await client.request({
+        type: 'write',
+        requestId: randomUUID(),
+        sessionId,
+        data,
+      });
+      requireResponse(response, 'written');
+      break;
+    }
+    case 'follow': {
+      const [sessionId] = commandArguments;
+      if (!sessionId) {
+        throw new Error('follow requires a session ID.');
+      }
+      const response = await client.request({
+        type: 'observe',
+        requestId: randomUUID(),
+        sessionId,
+      });
+      requireResponse(response, 'observing');
+      process.stdout.write(response.history);
+
+      if (response.session.state === 'exited') {
+        console.error(
+          `\nSession has already exited with code ${
+            response.session.exitCode ?? 'unknown'
+          }.`,
+        );
+      } else {
+        await new Promise((resolve) => {
+          const finish = () => {
+            unsubscribe();
+            resolve();
+          };
+          const unsubscribe = client.onMessage((message) => {
+            if (message.type === 'output' && message.sessionId === sessionId) {
+              process.stdout.write(message.data);
+            } else if (
+              message.type === 'exit' &&
+              message.sessionId === sessionId
+            ) {
+              console.error(`\nSession exited with code ${message.exitCode}.`);
+              finish();
+            } else if (
+              message.type === 'sessions' &&
+              !message.sessions.some((session) => session.id === sessionId)
+            ) {
+              console.error('\nSession was closed.');
+              finish();
+            }
+          });
+          process.once('SIGINT', finish);
+          client.onceClosed(finish);
+        });
+      }
+      if (client.connected) {
+        await client.request({
+          type: 'unobserve',
+          requestId: randomUUID(),
+          sessionId,
+        });
+      }
+      break;
+    }
+    case 'close': {
+      const [sessionId] = commandArguments;
+      if (!sessionId) {
+        throw new Error('close requires a session ID.');
+      }
+      const response = await client.request({
+        type: 'close',
+        requestId: randomUUID(),
+        sessionId,
+      });
+      requireResponse(response, 'closed');
+      break;
+    }
+    default:
+      throw new Error(`Unknown command: ${command}`);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+} finally {
+  client.close();
+}
+}
+
+class SessionWireClient {
+  #socket;
+  #pending = new Map();
+  #listeners = new Set();
+  #closeListeners = new Set();
+  #sessions;
+  #sessionWaiters = [];
+
+  constructor(url, token) {
+    this.url = url;
+    this.token = token;
+  }
+
+  get connected() {
+    return this.#socket?.readyState === WebSocket.OPEN;
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      const headers = this.token
+        ? { Authorization: `Bearer ${this.token}` }
+        : undefined;
+      const socket = new WebSocket(this.url, { headers });
+      this.#socket = socket;
+      socket.once('open', resolve);
+      socket.once('error', reject);
+      socket.on('message', (raw) => this.#handle(JSON.parse(raw.toString())));
+      socket.on('close', () => {
+        for (const pending of this.#pending.values()) {
+          pending.reject(new Error('Terminal connection closed.'));
+        }
+        this.#pending.clear();
+        for (const listener of this.#closeListeners) {
+          listener();
+        }
+      });
+    });
+  }
+
+  request(message) {
+    if (!this.connected) {
+      return Promise.reject(new Error('Terminal CLI is not connected.'));
+    }
+    return new Promise((resolve, reject) => {
+      this.#pending.set(message.requestId, { resolve, reject });
+      this.#socket.send(JSON.stringify(message));
+    });
+  }
+
+  waitForSessions() {
+    if (this.#sessions) {
+      return Promise.resolve(this.#sessions);
+    }
+    return new Promise((resolve) => this.#sessionWaiters.push(resolve));
+  }
+
+  onMessage(listener) {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  onceClosed(listener) {
+    this.#closeListeners.add(listener);
+  }
+
+  close() {
+    this.#socket?.close(1000, 'CLI completed');
+  }
+
+  #handle(message) {
+    if (message.type === 'sessions') {
+      this.#sessions = message.sessions;
+      for (const resolve of this.#sessionWaiters.splice(0)) {
+        resolve(message.sessions);
+      }
+    }
+
+    if (message.type === 'error') {
+      if (message.requestId) {
+        const pending = this.#pending.get(message.requestId);
+        this.#pending.delete(message.requestId);
+        pending?.reject(new Error(message.message));
+      } else {
+        console.error(message.message);
+      }
+      return;
+    }
+
+    if (message.requestId) {
+      const pending = this.#pending.get(message.requestId);
+      this.#pending.delete(message.requestId);
+      pending?.resolve(message);
+    }
+
+    for (const listener of this.#listeners) {
+      listener(message);
+    }
+  }
+}
+
+function parseArguments(args) {
+  const remaining = [];
+  let url =
+    process.env.WEB_TERMINAL_URL ?? 'ws://127.0.0.1:5173/terminal';
+  let token = process.env.WEB_TERMINAL_TOKEN;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--url') {
+      url = requireOptionValue(args, ++index, '--url');
+    } else if (argument === '--token') {
+      token = requireOptionValue(args, ++index, '--token');
+    } else {
+      remaining.push(argument);
+    }
+  }
+
+  return {
+    command: remaining[0],
+    arguments: remaining.slice(1),
+    url,
+    token,
+  };
+}
+
+function requireOptionValue(args, index, option) {
+  const value = args[index];
+  if (!value) {
+    throw new Error(`${option} requires a value.`);
+  }
+  return value;
+}
+
+function requireResponse(response, expectedType) {
+  if (response.type !== expectedType) {
+    throw new Error(
+      `Expected ${expectedType}, received ${response.type ?? 'unknown'}.`,
+    );
+  }
+}
+
+function printHelp() {
+  console.log(`Usage: web-terminal [--url URL] [--token TOKEN] <command>
+
+Commands:
+  sessions                     List visible sessions
+  open [name]                  Open a named session and print its ID
+  send <session-id> <command>  Write a command followed by Enter
+  write <session-id> <data>    Write exact input without Enter
+  follow <session-id>          Print history and follow live output
+  close <session-id>           Permanently close a session
+
+Environment:
+  WEB_TERMINAL_URL
+  WEB_TERMINAL_TOKEN`);
+}
+
+await main();

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createTerminalClient, TerminalClient, type DisplayOptions, type OpenOptions, type TerminalClientEvent, type TerminalClientOptions, } from './terminal-client.js';
+export { TerminalView } from './terminal-view.js';
+export type { ClientMessage, ServerMessage, SessionSummary, } from './protocol.js';

package/dist/protocol.d.ts

@@ -0,0 +1,98 @@
+export interface SessionSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly state: 'running' | 'exited';
+    readonly attached: boolean;
+    readonly observers: number;
+    readonly createdAt: string;
+    readonly lastActiveAt: string;
+    readonly exitCode?: number;
+}
+export type ClientMessage = {
+    type: 'open';
+    requestId: string;
+    name?: string;
+} | {
+    type: 'close';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'attach';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'detach';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'write';
+    requestId: string;
+    sessionId: string;
+    data: string;
+} | {
+    type: 'observe';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'unobserve';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'input';
+    sessionId: string;
+    data: string;
+} | {
+    type: 'resize';
+    sessionId: string;
+    cols: number;
+    rows: number;
+};
+export type ServerMessage = {
+    type: 'sessions';
+    sessions: SessionSummary[];
+} | {
+    type: 'opened';
+    requestId: string;
+    session: SessionSummary;
+} | {
+    type: 'closed';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'attached';
+    requestId: string;
+    session: SessionSummary;
+    history: string;
+} | {
+    type: 'detached';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'written';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'observing';
+    requestId: string;
+    session: SessionSummary;
+    history: string;
+} | {
+    type: 'unobserved';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'output';
+    sessionId: string;
+    data: string;
+} | {
+    type: 'exit';
+    sessionId: string;
+    exitCode: number;
+    signal?: number;
+} | {
+    type: 'error';
+    message: string;
+    requestId?: string;
+};
+export declare function parseClientMessage(value: unknown): ClientMessage | undefined;
+export declare function parseServerMessage(value: unknown): ServerMessage | undefined;

package/dist/terminal-client.d.ts

@@ -0,0 +1,62 @@
+import type { ITerminalOptions } from '@xterm/xterm';
+import { type SessionSummary } from './protocol.js';
+import { TerminalView } from './terminal-view.js';
+export interface TerminalClientOptions {
+    socketUrl: string | (() => string);
+    autoConnect?: boolean;
+    onError?: (error: Error) => void;
+}
+export interface OpenOptions {
+    name?: string;
+}
+export interface DisplayOptions {
+    terminalOptions?: ITerminalOptions;
+}
+export interface TerminalClientEvent {
+    readonly type: 'connected' | 'disconnected' | 'opened' | 'attached' | 'detached' | 'closed' | 'exit';
+    readonly sessionId?: string;
+    readonly exitCode?: number;
+}
+export declare class TerminalClient {
+    private readonly options;
+    private readonly sessionListeners;
+    private readonly eventListeners;
+    private readonly pending;
+    private socket;
+    private connectPromise;
+    private sessionSnapshot;
+    private attachedSessionId;
+    private view;
+    private viewSessionId;
+    private bufferedOutput;
+    constructor(options: TerminalClientOptions);
+    get sessions(): readonly SessionSummary[];
+    get connected(): boolean;
+    get attachedSession(): string | undefined;
+    connect(): Promise<void>;
+    disconnect(): void;
+    open(options?: OpenOptions): Promise<SessionSummary>;
+    close(sessionId: string): Promise<void>;
+    write(sessionId: string, data: string): Promise<void>;
+    attach(sessionId: string): Promise<{
+        session: SessionSummary;
+        history: string;
+    }>;
+    detach(): Promise<void>;
+    private detachSession;
+    display(sessionId: string, target: HTMLElement, options?: DisplayOptions): Promise<TerminalView>;
+    subscribeSessions(listener: (sessions: readonly SessionSummary[]) => void): () => void;
+    subscribeEvents(listener: (event: TerminalClientEvent) => void): () => void;
+    dispose(): void;
+    private input;
+    private resize;
+    private releaseView;
+    private disposeView;
+    private request;
+    private send;
+    private handleMessage;
+    private rejectPending;
+    private emitEvent;
+    private reportError;
+}
+export declare function createTerminalClient(options: TerminalClientOptions): TerminalClient;

package/dist/terminal-view.d.ts

@@ -0,0 +1,28 @@
+import { Terminal, type ITerminalOptions } from '@xterm/xterm';
+import '@xterm/xterm/css/xterm.css';
+import './web-terminal.css';
+export interface TerminalViewController {
+    input(data: string): void;
+    resize(cols: number, rows: number): void;
+    release(view: TerminalView): void;
+}
+export interface TerminalViewOptions {
+    target: HTMLElement;
+    controller: TerminalViewController;
+    terminalOptions?: ITerminalOptions;
+}
+export declare class TerminalView {
+    readonly terminal: Terminal;
+    private readonly fitAddon;
+    private readonly target;
+    private readonly controller;
+    private readonly resizeObserver;
+    private disposed;
+    constructor(options: TerminalViewOptions);
+    write(data: string): void;
+    focus(): void;
+    fit(): void;
+    dispose(): void;
+    disposeVisuals(): void;
+    private assertActive;
+}

package/dist/web-terminal.css

@@ -0,0 +1,2 @@
+.xterm{cursor:text;-webkit-user-select:none;user-select:none;position:relative}.xterm.focus,.xterm:focus{outline:none}.xterm .xterm-helpers{z-index:5;position:absolute;top:0}.xterm .xterm-helper-textarea{opacity:0;z-index:-5;white-space:nowrap;resize:none;border:0;width:0;height:0;margin:0;padding:0;position:absolute;top:0;left:-9999em;overflow:hidden}.xterm .composition-view{color:#fff;white-space:nowrap;z-index:1;background:#000;display:none;position:absolute}.xterm .composition-view.active{display:block}.xterm .xterm-viewport{cursor:default;background-color:#000;position:absolute;inset:0;overflow-y:scroll}.xterm .xterm-screen{position:relative}.xterm .xterm-screen canvas{position:absolute;top:0;left:0}.xterm-char-measure-element{visibility:hidden;line-height:normal;display:inline-block;position:absolute;top:0;left:-9999em}.xterm.enable-mouse-events{cursor:default}.xterm.xterm-cursor-pointer,.xterm .xterm-cursor-pointer{cursor:pointer}.xterm.column-select.focus{cursor:crosshair}.xterm .xterm-accessibility:not(.debug),.xterm .xterm-message{z-index:10;color:#0000;pointer-events:none;position:absolute;inset:0}.xterm .xterm-accessibility-tree:not(.debug) ::selection{color:#0000}.xterm .xterm-accessibility-tree{-webkit-user-select:text;user-select:text;white-space:pre;font-family:monospace}.xterm .xterm-accessibility-tree>div{transform-origin:0;width:fit-content}.xterm .live-region{width:1px;height:1px;position:absolute;left:-9999px;overflow:hidden}.xterm-dim{opacity:1!important}.xterm-underline-1{text-decoration:underline}.xterm-underline-2{-webkit-text-decoration:underline double;text-decoration:underline double}.xterm-underline-3{-webkit-text-decoration:underline wavy;text-decoration:underline wavy}.xterm-underline-4{-webkit-text-decoration:underline dotted;text-decoration:underline dotted}.xterm-underline-5{-webkit-text-decoration:underline dashed;text-decoration:underline dashed}.xterm-overline{text-decoration:overline}.xterm-overline.xterm-underline-1{text-decoration:underline overline}.xterm-overline.xterm-underline-2{-webkit-text-decoration:overline double underline;text-decoration:overline double underline}.xterm-overline.xterm-underline-3{-webkit-text-decoration:overline wavy underline;text-decoration:overline wavy underline}.xterm-overline.xterm-underline-4{-webkit-text-decoration:overline dotted underline;text-decoration:overline dotted underline}.xterm-overline.xterm-underline-5{-webkit-text-decoration:overline dashed underline;text-decoration:overline dashed underline}.xterm-strikethrough{text-decoration:line-through}.xterm-screen .xterm-decoration-container .xterm-decoration{z-index:6;position:absolute}.xterm-screen .xterm-decoration-container .xterm-decoration.xterm-decoration-top-layer{z-index:7}.xterm-decoration-overview-ruler{z-index:8;pointer-events:none;position:absolute;top:0;right:0}.xterm-decoration-top{z-index:2;position:relative}.xterm .xterm-scrollable-element>.scrollbar{cursor:default}.xterm .xterm-scrollable-element>.scrollbar>.scra{cursor:pointer;font-size:11px!important}.xterm .xterm-scrollable-element>.visible{opacity:1;z-index:11;background:0 0;transition:opacity .1s linear}.xterm .xterm-scrollable-element>.invisible{opacity:0;pointer-events:none}.xterm .xterm-scrollable-element>.invisible.fade{transition:opacity .8s linear}.xterm .xterm-scrollable-element>.shadow{display:none;position:absolute}.xterm .xterm-scrollable-element>.shadow.top{width:100%;height:3px;box-shadow:var(--vscode-scrollbar-shadow,#000) 0 6px 6px -6px inset;display:block;top:0;left:3px}.xterm .xterm-scrollable-element>.shadow.left{width:3px;height:100%;box-shadow:var(--vscode-scrollbar-shadow,#000) 6px 0 6px -6px inset;display:block;top:3px;left:0}.xterm .xterm-scrollable-element>.shadow.top-left-corner{width:3px;height:3px;display:block;top:0;left:0}.xterm .xterm-scrollable-element>.shadow.top.left{box-shadow:var(--vscode-scrollbar-shadow,#000) 6px 0 6px -6px inset}.web-terminal{box-sizing:border-box;background:#111318;min-width:0;min-height:0;overflow:hidden}.web-terminal .xterm{height:100%;padding:12px}.web-terminal .xterm-viewport{scrollbar-color:#434957 transparent;scrollbar-width:thin}
+/*$vite$:1*/