@jacksontian/mwt 1.0.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # mwt - Multi-Window Terminal
 
-A lightweight web-based multi-window terminal for **local development**. Run multiple shell sessions in the browser with side-by-side, grid, and tab layouts.
+A lightweight web-based multi-window terminal for **local development**. Run multiple shell sessions in the browser with columns, rows, grid, and tab layouts.
 
 > **Note:** mwt is designed for local use on your development machine. It does not provide authentication, encryption, or any access control — do not expose it to the network.
 
@@ -9,9 +9,13 @@ A lightweight web-based multi-window terminal for **local development**. Run mul
 [![Node.js](https://img.shields.io/node/v/@jacksontian/mwt)](https://nodejs.org)
 [![License](https://img.shields.io/npm/l/@jacksontian/mwt)](LICENSE)
 
-### Side by Side
+### Columns
 
-![Side by Side](./figures/sidebyside.png)
+![Columns](./figures/columns.png)
+
+### Rows
+
+![Rows](./figures/rows.png)
 
 ### Grid
 
@@ -42,15 +46,15 @@ mwt 想解决的问题很简单：**给本地开发提供一个轻量、直觉
 
 **浏览器即界面** — 选择浏览器作为 UI 层，天然跨平台，不需要安装桌面应用。布局切换、主题跟随、快捷键操作都在浏览器中完成，所见即所得。
 
-**会话不丢失** — 每个终端保留 100KB 的输出缓冲区，刷新页面或网络断开后可以恢复现场。断线 30 分钟内自动重连，开发流程不被打断。
+**会话不丢失** — 每个终端保留 100KB 的输出缓冲区，刷新页面或网络断开后可以恢复现场；断线 30 分钟内服务端保留会话，自动重连后回放缓冲。**同一 `sessionId` 同时只允许一个标签页保持 WebSocket**，新开标签页会被拒绝，避免多页争抢同一组 PTY。详见下文 **Session & recovery**。
 
 **够用就好** — 不做 SSH、不做认证、不做插件系统。mwt 只专注于一件事：在本地高效地管理多个终端窗口。功能边界清晰，代码量控制在 2000 行左右，任何人都可以快速理解和修改。
 
 ## Features
 
 - **Multi-terminal** - Create and manage multiple terminal sessions simultaneously
-- **Three layouts** - Side-by-side, grid, and tabs, switch anytime
-- **Session persistence** - Reconnect without losing terminal output (100KB buffer per terminal)
+- **Four layouts** - Columns, rows, grid, and tabs, switch anytime
+- **Session persistence** - Reconnect without losing recent terminal output (100KB buffer per terminal); **one browser tab** may be connected per session (see **Session & recovery**)
 - **Auto-reconnect** - WebSocket disconnection recovery with exponential backoff
 - **Dark / Light theme** - Manual toggle or follow system preference
 - **Keyboard-driven** - Full keyboard shortcut support
@@ -87,6 +91,20 @@ Example:
 mwt -p 8080
 ```
 
+## Session & recovery
+
+Understanding how the browser talks to the server avoids surprises (especially with multiple tabs).
+
+| Topic | Behavior |
+|--------|----------|
+| **Session ID** | On first visit, the page stores a UUID in `localStorage` under `myterminal-session-id`. Every WebSocket connection sends this id so the server can attach to the same logical session (same PTY processes) after a refresh. |
+| **Single active tab (互斥连接)** | Only **one** browser tab may keep the WebSocket open for that session. If you open mwt in a **second** tab while the first is still connected, the new tab’s connection is **rejected** and you see a full-page message: *mwt is already open in another tab.* This is intentional: two tabs would both try to drive the same shells. Close the other tab or use one tab only. |
+| **Refresh & reconnect** | Reloading the **same** tab disconnects briefly, then reconnects with the same `sessionId`. Existing terminal ids are restored; the server replays recent output from its per-terminal ring buffer (see below). |
+| **Output buffer** | While connected, the server keeps the **last ~100 KB** of output per terminal. After reconnect, that chunk is sent to the client so you don’t lose recent scrollback. It is not a full session log. |
+| **Idle cleanup** | If **no** tab is connected for **30 minutes**, the server **kills** that session’s shells and clears its state. The next visit still uses the same `sessionId` in `localStorage`, but you’ll get an **empty** session (no old terminals)—create new ones as needed. |
+
+**Summary:** one tab connected at a time; refresh is fine; a second simultaneous tab is blocked; long disconnects drop server-side sessions after 30 minutes.
+
 ## Keyboard Shortcuts
 
 | Shortcut | Action |

package/lib/pty-manager.js

@@ -0,0 +1,40 @@
+import pty from 'node-pty';
+import { RingBuffer } from './ring-buffer.js';
+
+const OUTPUT_BUFFER_SIZE = 100 * 1024; // 100KB per terminal
+
+/**
+ * Spawn a PTY process and attach it to a session terminal slot.
+ * Returns the terminal entry { pty, outputBuffer } on success,
+ * or null if spawn fails (the caller receives an 'exit' message).
+ */
+export function spawnTerminal({ id, cols, rows, cwd, onData, onExit }) {
+  const shell = process.env.SHELL || '/bin/bash';
+  let ptyProcess;
+  try {
+    ptyProcess = pty.spawn(shell, [], {
+      name: 'xterm-256color',
+      cols: cols || 80,
+      rows: rows || 24,
+      cwd,
+      env: process.env,
+    });
+  } catch (err) {
+    console.error(`Failed to spawn shell "${shell}":`, err.message);
+    onExit(id, 1);
+    return null;
+  }
+
+  const outputBuffer = new RingBuffer(OUTPUT_BUFFER_SIZE);
+
+  ptyProcess.onData((data) => {
+    outputBuffer.write(data);
+    onData(id, data);
+  });
+
+  ptyProcess.onExit(({ exitCode }) => {
+    onExit(id, exitCode);
+  });
+
+  return { pty: ptyProcess, outputBuffer };
+}

package/lib/ring-buffer.js

@@ -32,7 +32,7 @@ export class RingBuffer {
   }
 
   read() {
-    if (this.length === 0) return '';
+    if (this.length === 0) {return '';}
 
     if (this.length < this.capacity) {
       // Haven't wrapped yet — data starts at 0

package/lib/server.js

@@ -2,10 +2,10 @@ import { createServer } from 'node:http';
 import { readFile } from 'node:fs/promises';
 import { join, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { exec } from 'node:child_process';
+import { execFile } from 'node:child_process';
 import { WebSocketServer } from 'ws';
-import pty from 'node-pty';
-import { RingBuffer } from './ring-buffer.js';
+import { SessionManager } from './session-manager.js';
+import { spawnTerminal } from './pty-manager.js';
 
 const __dirname = fileURLToPath(new URL('..', import.meta.url));
 
@@ -21,192 +21,178 @@ const MIME_TYPES = {
   '.ico': 'image/x-icon',
 };
 
-const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
-const CLEANUP_INTERVAL_MS = 60 * 1000;     // check every minute
-const OUTPUT_BUFFER_SIZE = 100 * 1024;      // 100KB per terminal
-
 function openBrowser(url) {
   const cmd = process.platform === 'darwin' ? 'open'
-    : process.platform === 'win32' ? 'start'
-    : 'xdg-open';
-  exec(`${cmd} ${url}`);
+    : process.platform === 'win32' ? 'cmd'
+      : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', url] : [url];
+  execFile(cmd, args);
 }
 
 export function start(port = 1987, host = '127.0.0.1', options = {}) {
+  const startCwd = process.cwd();
+  const sessions = new SessionManager();
+
+  const publicDir = join(__dirname, 'public');
+  const SECURITY_HEADERS = {
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+    'Cache-Control': 'no-store',
+  };
+
+  // HTTP server for static files
+  const server = createServer(async (req, res) => {
+    let filePath;
+    const url = req.url.split('?')[0];
+
+    if (url === '/') {
+      filePath = join(publicDir, 'index.html');
+    } else {
+      filePath = join(publicDir, url);
+    }
 
-const startCwd = process.cwd();
-const sessions = new Map(); // sessionId -> { terminals, ws, disconnectedAt }
-
-// HTTP server for static files
-const server = createServer(async (req, res) => {
-  let filePath;
-  const url = req.url.split('?')[0];
-
-  if (url === '/') {
-    filePath = join(__dirname, 'public', 'index.html');
-  } else {
-    filePath = join(__dirname, 'public', url);
-  }
+    // Prevent path traversal: resolved path must stay within publicDir
+    if (!filePath.startsWith(publicDir + '/') && filePath !== join(publicDir, 'index.html')) {
+      res.writeHead(403, { 'Content-Type': 'text/plain', ...SECURITY_HEADERS });
+      res.end('Forbidden');
+      return;
+    }
 
-  try {
-    const data = await readFile(filePath);
+    // Only serve known file types
     const ext = extname(filePath);
-    res.writeHead(200, { 'Content-Type': MIME_TYPES[ext] || 'application/octet-stream' });
-    res.end(data);
-  } catch {
-    res.writeHead(404, { 'Content-Type': 'text/plain' });
-    res.end('Not Found');
-  }
-});
-
-// WebSocket server
-const wss = new WebSocketServer({ server });
-
-wss.on('connection', (ws, req) => {
-  const url = new URL(req.url, 'http://localhost');
-  const sessionId = url.searchParams.get('sessionId');
-  if (!sessionId) {
-    ws.close(4001, 'Missing sessionId');
-    return;
-  }
-
-  let session = sessions.get(sessionId);
-  if (!session) {
-    session = { terminals: new Map(), ws: null, disconnectedAt: null };
-    sessions.set(sessionId, session);
-  }
-
-  // Detach old WS if still open
-  if (session.ws && session.ws !== ws && session.ws.readyState === 1) {
-    session.ws.close();
-  }
-
-  session.ws = ws;
-  session.disconnectedAt = null;
-
-  // Send session-restore with existing terminal IDs
-  const terminalIds = [...session.terminals.keys()];
-  ws.send(JSON.stringify({ type: 'session-restore', terminals: terminalIds }));
-
-  // Send buffered output for each existing terminal
-  for (const [id, entry] of session.terminals) {
-    const buffered = entry.outputBuffer.read();
-    if (buffered) {
-      ws.send(JSON.stringify({ type: 'buffer', id, data: buffered }));
+    if (!MIME_TYPES[ext]) {
+      res.writeHead(403, { 'Content-Type': 'text/plain', ...SECURITY_HEADERS });
+      res.end('Forbidden');
+      return;
     }
-  }
-
-  // Signal that all buffer messages have been sent
-  if (terminalIds.length > 0) {
-    ws.send(JSON.stringify({ type: 'restore-complete' }));
-  }
 
-  ws.on('message', async (raw) => {
-    let msg;
     try {
-      msg = JSON.parse(raw);
+      const data = await readFile(filePath);
+      res.writeHead(200, { 'Content-Type': MIME_TYPES[ext], ...SECURITY_HEADERS });
+      res.end(data);
     } catch {
+      res.writeHead(404, { 'Content-Type': 'text/plain', ...SECURITY_HEADERS });
+      res.end('Not Found');
+    }
+  });
+
+  // WebSocket server
+  const wss = new WebSocketServer({ server });
+
+  wss.on('connection', (ws, req) => {
+    const url = new URL(req.url, 'http://localhost');
+    const sessionId = url.searchParams.get('sessionId');
+    if (!sessionId) {
+      ws.close(4001, 'Missing sessionId');
       return;
     }
 
-    switch (msg.type) {
-      case 'create': {
-        const shell = process.env.SHELL || '/bin/bash';
-        let ptyProcess;
-        try {
-          ptyProcess = pty.spawn(shell, [], {
-            name: 'xterm-256color',
-            cols: msg.cols || 80,
-            rows: msg.rows || 24,
-            cwd: startCwd,
-            env: process.env,
-          });
-        } catch (err) {
-          console.error(`Failed to spawn shell "${shell}":`, err.message);
-          if (ws.readyState === 1) {
-            ws.send(JSON.stringify({ type: 'exit', id: msg.id, exitCode: 1 }));
-          }
-          break;
-        }
+    const session = sessions.getOrCreate(sessionId);
 
-        const outputBuffer = new RingBuffer(OUTPUT_BUFFER_SIZE);
-        session.terminals.set(msg.id, { pty: ptyProcess, outputBuffer });
+    // Reject new connection if session already has an active WebSocket
+    if (session.ws && session.ws.readyState === 1) {
+      ws.close(4409, 'already connected');
+      return;
+    }
 
-        ptyProcess.onData((data) => {
-          outputBuffer.write(data);
-          if (session.ws && session.ws.readyState === 1) {
-            session.ws.send(JSON.stringify({ type: 'data', id: msg.id, data }));
-          }
-        });
+    sessions.connect(session, ws);
 
-        ptyProcess.onExit(({ exitCode }) => {
-          session.terminals.delete(msg.id);
-          if (session.ws && session.ws.readyState === 1) {
-            session.ws.send(JSON.stringify({ type: 'exit', id: msg.id, exitCode }));
-          }
-        });
-        break;
+    // Send session-restore with existing terminal IDs
+    const terminalIds = [...session.terminals.keys()];
+    ws.send(JSON.stringify({ type: 'session-restore', terminals: terminalIds }));
+
+    // Send buffered output for each existing terminal
+    for (const [id, entry] of session.terminals) {
+      const buffered = entry.outputBuffer.read();
+      if (buffered) {
+        ws.send(JSON.stringify({ type: 'buffer', id, data: buffered }));
       }
+    }
+
+    // Signal that all buffer messages have been sent
+    if (terminalIds.length > 0) {
+      ws.send(JSON.stringify({ type: 'restore-complete' }));
+    }
 
-      case 'data': {
-        const entry = session.terminals.get(msg.id);
-        if (entry) entry.pty.write(msg.data);
-        break;
+    ws.on('message', async (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw);
+      } catch {
+        return;
       }
 
-      case 'resize': {
-        const entry = session.terminals.get(msg.id);
-        if (entry) {
-          try {
-            entry.pty.resize(msg.cols, msg.rows);
-          } catch {
-            // ignore invalid resize
+      switch (msg.type) {
+        case 'create': {
+          const entry = spawnTerminal({
+            id: msg.id,
+            cols: msg.cols,
+            rows: msg.rows,
+            cwd: startCwd,
+            onData: (id, data) => {
+              if (session.ws && session.ws.readyState === 1) {
+                session.ws.send(JSON.stringify({ type: 'data', id, data }));
+              }
+            },
+            onExit: (id, exitCode) => {
+              sessions.deleteTerminal(session, id);
+              if (session.ws && session.ws.readyState === 1) {
+                session.ws.send(JSON.stringify({ type: 'exit', id, exitCode }));
+              }
+            },
+          });
+          if (entry) {
+            session.terminals.set(msg.id, entry);
           }
+          break;
         }
-        break;
-      }
 
-      case 'close': {
-        const entry = session.terminals.get(msg.id);
-        if (entry) {
-          entry.pty.kill();
-          session.terminals.delete(msg.id);
+        case 'data': {
+          const entry = session.terminals.get(msg.id);
+          if (entry) { entry.pty.write(msg.data); }
+          break;
+        }
+
+        case 'resize': {
+          const entry = session.terminals.get(msg.id);
+          if (entry) {
+            try {
+              entry.pty.resize(msg.cols, msg.rows);
+            } catch {
+              // ignore invalid resize
+            }
+          }
+          break;
+        }
+
+        case 'close': {
+          const entry = session.terminals.get(msg.id);
+          if (entry) {
+            entry.pty.kill();
+            sessions.deleteTerminal(session, msg.id);
+          }
+          break;
         }
-        break;
       }
+    });
 
-    }
+    ws.on('close', () => {
+      sessions.disconnect(session, ws);
+    });
   });
 
-  ws.on('close', () => {
-    if (session.ws === ws) {
-      session.ws = null;
-      session.disconnectedAt = Date.now();
+  server.listen(port, host, () => {
+    const url = `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${port}`;
+    console.log(`mwt running at ${url}`);
+    if (options.open !== false) {
+      openBrowser(url);
     }
   });
-});
-
-server.listen(port, host, () => {
-  const url = `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${port}`;
-  console.log(`mwt running at ${url}`);
-  if (options.open !== false) {
-    openBrowser(url);
-  }
-});
-
-// Clean up sessions that have been disconnected too long
-const cleanupTimer = setInterval(() => {
-  const now = Date.now();
-  for (const [sessionId, session] of sessions) {
-    if (session.disconnectedAt && (now - session.disconnectedAt) > SESSION_TIMEOUT_MS) {
-      for (const [, entry] of session.terminals) {
-        entry.pty.kill();
-      }
-      session.terminals.clear();
-      sessions.delete(sessionId);
-    }
-  }
-}, CLEANUP_INTERVAL_MS);
-cleanupTimer.unref();
 
-} // end start
+  // Kill all PTY processes on exit to avoid orphan processes
+  function killAll() { sessions.killAll(); }
+
+  process.once('exit', killAll);
+  process.once('SIGINT', () => { killAll(); process.exit(130); });
+  process.once('SIGTERM', () => { killAll(); process.exit(143); });
+}

package/lib/session-manager.js

@@ -0,0 +1,66 @@
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const CLEANUP_INTERVAL_MS = 60 * 1000;     // check every minute
+
+export class SessionManager {
+  constructor() {
+    this._sessions = new Map(); // sessionId -> { terminals, ws, disconnectedAt }
+
+    const timer = setInterval(() => this._cleanup(), CLEANUP_INTERVAL_MS);
+    timer.unref();
+  }
+
+  /** Return existing session or create a new one. */
+  getOrCreate(sessionId) {
+    let session = this._sessions.get(sessionId);
+    if (!session) {
+      session = { terminals: new Map(), ws: null, disconnectedAt: null };
+      this._sessions.set(sessionId, session);
+    }
+    return session;
+  }
+
+  get(sessionId) {
+    return this._sessions.get(sessionId);
+  }
+
+  /** Mark a session as connected to the given WebSocket. */
+  connect(session, ws) {
+    session.ws = ws;
+    session.disconnectedAt = null;
+  }
+
+  /** Mark a session as disconnected. */
+  disconnect(session, ws) {
+    if (session.ws === ws) {
+      session.ws = null;
+      session.disconnectedAt = Date.now();
+    }
+  }
+
+  /** Remove a terminal entry from a session. */
+  deleteTerminal(session, id) {
+    session.terminals.delete(id);
+  }
+
+  /** Kill all PTY processes across all sessions. */
+  killAll() {
+    for (const session of this._sessions.values()) {
+      for (const entry of session.terminals.values()) {
+        try { entry.pty.kill(); } catch {}
+      }
+    }
+  }
+
+  _cleanup() {
+    const now = Date.now();
+    for (const [sessionId, session] of this._sessions) {
+      if (session.disconnectedAt && (now - session.disconnectedAt) > SESSION_TIMEOUT_MS) {
+        for (const [, entry] of session.terminals) {
+          entry.pty.kill();
+        }
+        session.terminals.clear();
+        this._sessions.delete(sessionId);
+      }
+    }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jacksontian/mwt",
-  "version": "1.0.0",
-  "description": "Multi-window terminal with side-by-side, grid, and tab layouts",
+  "version": "1.2.0",
+  "description": "Multi-window terminal with columns, grid, and tab layouts",
   "type": "module",
   "bin": {
     "mwt": "bin/mwt.js"
@@ -21,7 +21,9 @@
   "scripts": {
     "test": "mocha",
     "cov": "c8 mocha",
-    "cov:report": "c8 report --reporter=text --reporter=html"
+    "cov:report": "c8 report --reporter=text --reporter=html",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
   },
   "engines": {
     "node": ">=18"
@@ -31,7 +33,10 @@
     "ws": "^8.18.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "c8": "^11.0.0",
+    "eslint": "^10.1.0",
+    "globals": "^17.4.0",
     "mocha": "^11.7.5"
   },
   "publishConfig": {