@jhebe/web-terminal 0.2.0

package/dist-server/src/protocol.js

@@ -0,0 +1,199 @@
+export function parseClientMessage(value) {
+    const message = parseRecord(value);
+    if (!message || typeof message.type !== 'string') {
+        return undefined;
+    }
+    switch (message.type) {
+        case 'open':
+            return hasRequestId(message) &&
+                (message.name === undefined || typeof message.name === 'string')
+                ? {
+                    type: 'open',
+                    requestId: message.requestId,
+                    ...(message.name === undefined ? {} : { name: message.name }),
+                }
+                : undefined;
+        case 'close':
+        case 'attach':
+        case 'observe':
+        case 'unobserve':
+            return hasRequestId(message) && typeof message.sessionId === 'string'
+                ? {
+                    type: message.type,
+                    requestId: message.requestId,
+                    sessionId: message.sessionId,
+                }
+                : undefined;
+        case 'detach':
+            return hasRequestId(message) && typeof message.sessionId === 'string'
+                ? {
+                    type: 'detach',
+                    requestId: message.requestId,
+                    sessionId: message.sessionId,
+                }
+                : undefined;
+        case 'write':
+            return hasRequestId(message) &&
+                typeof message.sessionId === 'string' &&
+                typeof message.data === 'string'
+                ? {
+                    type: 'write',
+                    requestId: message.requestId,
+                    sessionId: message.sessionId,
+                    data: message.data,
+                }
+                : undefined;
+        case 'input':
+            return typeof message.sessionId === 'string' &&
+                typeof message.data === 'string'
+                ? {
+                    type: 'input',
+                    sessionId: message.sessionId,
+                    data: message.data,
+                }
+                : undefined;
+        case 'resize':
+            return typeof message.sessionId === 'string' &&
+                validDimension(message.cols) &&
+                validDimension(message.rows)
+                ? {
+                    type: 'resize',
+                    sessionId: message.sessionId,
+                    cols: message.cols,
+                    rows: message.rows,
+                }
+                : undefined;
+        default:
+            return undefined;
+    }
+}
+export function parseServerMessage(value) {
+    const message = parseRecord(value);
+    if (!message || typeof message.type !== 'string') {
+        return undefined;
+    }
+    switch (message.type) {
+        case 'sessions':
+            return Array.isArray(message.sessions) &&
+                message.sessions.every(isSessionSummary)
+                ? { type: 'sessions', sessions: message.sessions }
+                : undefined;
+        case 'opened':
+            return hasRequestId(message) && isSessionSummary(message.session)
+                ? {
+                    type: 'opened',
+                    requestId: message.requestId,
+                    session: message.session,
+                }
+                : undefined;
+        case 'closed':
+        case 'written':
+        case 'unobserved':
+            return hasRequestId(message) && typeof message.sessionId === 'string'
+                ? {
+                    type: message.type,
+                    requestId: message.requestId,
+                    sessionId: message.sessionId,
+                }
+                : undefined;
+        case 'observing':
+            return hasRequestId(message) &&
+                isSessionSummary(message.session) &&
+                typeof message.history === 'string'
+                ? {
+                    type: 'observing',
+                    requestId: message.requestId,
+                    session: message.session,
+                    history: message.history,
+                }
+                : undefined;
+        case 'attached':
+            return hasRequestId(message) &&
+                isSessionSummary(message.session) &&
+                typeof message.history === 'string'
+                ? {
+                    type: 'attached',
+                    requestId: message.requestId,
+                    session: message.session,
+                    history: message.history,
+                }
+                : undefined;
+        case 'detached':
+            return hasRequestId(message) && typeof message.sessionId === 'string'
+                ? {
+                    type: 'detached',
+                    requestId: message.requestId,
+                    sessionId: message.sessionId,
+                }
+                : undefined;
+        case 'output':
+            return typeof message.sessionId === 'string' &&
+                typeof message.data === 'string'
+                ? {
+                    type: 'output',
+                    sessionId: message.sessionId,
+                    data: message.data,
+                }
+                : undefined;
+        case 'exit':
+            return typeof message.sessionId === 'string' &&
+                typeof message.exitCode === 'number' &&
+                (message.signal === undefined || typeof message.signal === 'number')
+                ? {
+                    type: 'exit',
+                    sessionId: message.sessionId,
+                    exitCode: message.exitCode,
+                    ...(message.signal === undefined ? {} : { signal: message.signal }),
+                }
+                : undefined;
+        case 'error':
+            return typeof message.message === 'string' &&
+                (message.requestId === undefined ||
+                    typeof message.requestId === 'string')
+                ? {
+                    type: 'error',
+                    message: message.message,
+                    ...(message.requestId === undefined
+                        ? {}
+                        : { requestId: message.requestId }),
+                }
+                : undefined;
+        default:
+            return undefined;
+    }
+}
+function parseRecord(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSessionSummary(value) {
+    return (isRecord(value) &&
+        typeof value.id === 'string' &&
+        typeof value.name === 'string' &&
+        (value.state === 'running' || value.state === 'exited') &&
+        typeof value.attached === 'boolean' &&
+        typeof value.observers === 'number' &&
+        typeof value.createdAt === 'string' &&
+        typeof value.lastActiveAt === 'string' &&
+        (value.exitCode === undefined || typeof value.exitCode === 'number'));
+}
+function hasRequestId(value) {
+    return typeof value.requestId === 'string';
+}
+function validDimension(value) {
+    return (typeof value === 'number' &&
+        Number.isInteger(value) &&
+        value > 0 &&
+        value <= 1000);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@jhebe/web-terminal",
+  "version": "0.2.0",
+  "description": "A framework-agnostic terminal session library for embedding managed terminals in web applications.",
+  "type": "module",
+  "files": [
+    "dist",
+    "dist-server",
+    "bin/web-terminal.mjs",
+    "scripts/prepare-node-pty.mjs"
+  ],
+  "bin": {
+    "web-terminal": "bin/web-terminal.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/web-terminal.js"
+    },
+    "./style.css": "./dist/web-terminal.css",
+    "./server": {
+      "types": "./dist-server/server/index.d.ts",
+      "import": "./dist-server/server/index.js"
+    }
+  },
+  "scripts": {
+    "postinstall": "node scripts/prepare-node-pty.mjs",
+    "clean": "rm -rf dist dist-server",
+    "build": "npm run clean && npm run build:client && npm run build:server",
+    "build:client": "vite build --config vite.config.ts && tsc -p tsconfig.client.json",
+    "build:server": "tsc -p tsconfig.server.json",
+    "check": "tsc -p tsconfig.check.json",
+    "test": "tsx --test test/*.test.ts"
+  },
+  "keywords": [
+    "terminal",
+    "web-terminal",
+    "xterm",
+    "pty",
+    "session"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
+    "node-pty": "^1.1.0",
+    "ws": "^8.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.23.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.1.4"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/prepare-node-pty.mjs

@@ -0,0 +1,28 @@
+import { chmod, readdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+
+if (process.platform !== 'win32') {
+  const require = createRequire(import.meta.url);
+  const prebuilds = join(
+    dirname(require.resolve('node-pty/package.json')),
+    'prebuilds',
+  );
+
+  for (const platformDirectory of await readdir(prebuilds, {
+    withFileTypes: true,
+  })) {
+    if (!platformDirectory.isDirectory()) {
+      continue;
+    }
+
+    const helper = join(prebuilds, platformDirectory.name, 'spawn-helper');
+    try {
+      await chmod(helper, 0o755);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+  }
+}