x-shell.js 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2025-01-09
+
+### Added
+
+- **Tabbed Terminals**: New `show-tabs` attribute enables multiple terminal tabs in a single component
+  - Each tab has independent WebSocket connection and terminal session
+  - Tab bar with status indicators and add/close buttons
+  - Dynamic labels showing shell or container name
+  - `createTab()`, `switchTab()`, `closeTab()` methods
+- **Join Existing Session**: Connection panel now shows "Join Existing Session" mode when sessions are available
+- **Prompt Refresh on Join**: Joining a session now triggers a fresh prompt display
+
+### Fixed
+
+- Fixed duplicate output when multiple tabs join the same session
+- Fixed session list not updating after spawning a session
+- Each client's data handler now correctly writes to its own tab's terminal
+
+## [1.0.0] - 2025-01-08
+
+### Added
+
+- Initial release
+- WebSocket-based terminal server with node-pty
+- Lightweight client library with auto-reconnection
+- `<x-shell-terminal>` Lit web component with xterm.js
+- Docker exec support for connecting to containers
+- Docker attach mode for connecting to container's main process (PID 1)
+- Session multiplexing - multiple clients sharing the same terminal
+- Session persistence with configurable orphan timeout
+- History replay for clients joining existing sessions
+- Built-in connection panel with container/shell selector
+- Settings dropdown (theme, font size)
+- Status bar with connection info
+- Dark/light/auto theme support
+- Security features: shell, path, and container allowlists
+- Python client bindings (`bindings/python/`)
+- Example projects for Docker containers and multiplexing

package/README.md

@@ -9,7 +9,12 @@ A plug-and-play terminal solution for web applications. Includes a server compon
 - **Server**: WebSocket server with node-pty for real shell sessions
 - **Client**: Lightweight WebSocket client with auto-reconnection
 - **UI**: `<x-shell-terminal>` Lit web component with xterm.js
-- **Docker**: Connect to Docker containers via `docker exec`
+- **Tabbed Terminals**: Multiple terminal tabs in a single component
+- **Docker Exec**: Connect to Docker containers via `docker exec`
+- **Docker Attach**: Connect to a container's main process (PID 1)
+- **Session Multiplexing**: Multiple clients can share the same terminal session
+- **Session Persistence**: Sessions survive client disconnects with configurable timeout
+- **History Replay**: New clients receive recent terminal output when joining
 - **Themes**: Built-in dark/light/auto theme support
 - **Security**: Configurable shell, path, and container allowlists
 - **Framework Agnostic**: Works with React, Vue, Angular, Svelte, or vanilla JS
@@ -58,7 +63,7 @@ The UI component can be loaded directly from a CDN - no build step required:
 <script type="module" src="https://cdn.jsdelivr.net/npm/x-shell.js/dist/ui/browser-bundle.js"></script>
 
 <!-- Pin to a specific version -->
-<script type="module" src="https://unpkg.com/x-shell.js@1.0.0-rc.1/dist/ui/browser-bundle.js"></script>
+<script type="module" src="https://unpkg.com/x-shell.js@1.0.0/dist/ui/browser-bundle.js"></script>
 ```
 
 The bundle includes the `<x-shell-terminal>` web component with xterm.js built-in.
@@ -169,6 +174,13 @@ const server = new TerminalServer({
 
   // Enable verbose logging
   verbose: false,
+
+  // Session multiplexing options
+  maxClientsPerSession: 10,     // Max clients per session (default: 10)
+  orphanTimeout: 60000,         // Ms before orphaned sessions close (default: 60000)
+  historySize: 50000,           // History buffer size in chars (default: 50000)
+  historyEnabled: true,         // Enable history replay (default: true)
+  maxSessionsTotal: 100,        // Max concurrent sessions (default: 100)
 });
 
 // Attach to HTTP server
@@ -235,6 +247,20 @@ client.isConnected();      // boolean
 client.hasActiveSession(); // boolean
 client.getSessionId();     // string | null
 client.getSessionInfo();   // SessionInfo | null
+
+// Session multiplexing
+const sessions = await client.listSessions();  // List all sessions
+const session = await client.join({            // Join existing session
+  sessionId: 'term-123...',
+  requestHistory: true,
+  historyLimit: 50000,
+});
+client.leave();                                // Leave without killing
+
+// Multiplexing event handlers
+client.onClientJoined((sessionId, count) => console.log(`${count} clients`));
+client.onClientLeft((sessionId, count) => console.log(`${count} clients`));
+client.onSessionClosed((sessionId, reason) => console.log(reason));
 ```
 
 ### UI Component
@@ -278,6 +304,7 @@ client.getSessionInfo();   // SessionInfo | null
 | `show-connection-panel` | boolean | `false` | Show connection panel with container/shell selector |
 | `show-settings` | boolean | `false` | Show settings dropdown (theme, font size) |
 | `show-status-bar` | boolean | `false` | Show status bar with connection info and errors |
+| `show-tabs` | boolean | `false` | Enable tabbed terminal interface |
 
 **Methods:**
 
@@ -292,6 +319,11 @@ terminal.clear();             // Clear display
 terminal.write('text');       // Write to display
 terminal.writeln('line');     // Write line to display
 terminal.focus();             // Focus terminal
+
+// Tab methods (when show-tabs is enabled)
+terminal.createTab('label');  // Create new tab
+terminal.switchTab('tab-id'); // Switch to tab
+terminal.closeTab('tab-id');  // Close tab
 ```
 
 **Events:**
@@ -328,6 +360,68 @@ The connection panel automatically queries the server for:
 ></x-shell-terminal>
 ```
 
+## Tabbed Terminals
+
+Enable multiple terminal tabs within a single component using the `show-tabs` attribute:
+
+```html
+<x-shell-terminal
+  url="ws://localhost:3000/terminal"
+  show-tabs
+  show-connection-panel
+  show-settings
+  show-status-bar
+></x-shell-terminal>
+```
+
+### Features
+
+- **Independent Sessions**: Each tab has its own WebSocket connection and terminal session
+- **Tab Bar**: Shows all open tabs with status indicators
+- **Dynamic Labels**: Tabs automatically update their label to show the shell or container name
+- **Session Joining**: Create a tab and join an existing session from another tab
+- **Easy Management**: Click "+" to add tabs, "×" to close, click tab to switch
+
+### Tab API
+
+```javascript
+const terminal = document.querySelector('x-shell-terminal');
+
+// Create a new tab
+const tab = terminal.createTab('My Terminal');
+// Returns: { id: 'tab-1', label: 'My Terminal', ... }
+
+// Switch to a specific tab
+terminal.switchTab('tab-1');
+
+// Close a tab (resources are cleaned up automatically)
+terminal.closeTab('tab-1');
+
+// Access tab state
+// Each tab maintains its own: client, terminal, sessionInfo, etc.
+```
+
+### Use Cases
+
+**1. Multi-Environment Development**
+```html
+<!-- Open tabs for different containers -->
+<x-shell-terminal show-tabs show-connection-panel></x-shell-terminal>
+```
+- Tab 1: Local shell for git operations
+- Tab 2: Docker container for backend
+- Tab 3: Docker container for frontend
+
+**2. Session Sharing**
+- Create a session in Tab 1
+- Create Tab 2, select "Join Existing Session"
+- Both tabs now mirror the same terminal
+
+**3. Monitoring Multiple Processes**
+- Open multiple tabs
+- Each tab connects to a different running session
+- Monitor all processes from a single interface
+
 ## Theming
 
 The component uses CSS custom properties for theming:
@@ -436,6 +530,178 @@ const server = new TerminalServer({
 });
 ```
 
+### Docker Attach Mode
+
+Docker attach connects to a container's main process (PID 1) instead of spawning a new shell. This is useful for:
+- Interacting with interactive containers started with `docker run -it`
+- Debugging container startup issues
+- Sharing a session with `docker attach` from another terminal
+
+```javascript
+// Client: Attach to container's main process
+await client.spawn({
+  container: 'my-container',
+  attachMode: true,  // Use docker attach instead of docker exec
+});
+```
+
+**Important:** Docker attach connects to whatever is running as PID 1. If the container was started with a non-interactive command (like a web server), attach may not provide useful interaction.
+
+```bash
+# Start an interactive container first
+docker run -it --name demo alpine sh
+
+# Then attach via x-shell
+# Both terminals now share the same shell session
+```
+
+## Session Multiplexing
+
+Session multiplexing allows multiple clients to connect to the same terminal session. This enables:
+- **Collaboration**: Multiple users can share a terminal
+- **Session Persistence**: Sessions survive client disconnects
+- **History Replay**: New clients receive recent output when joining
+- **Monitoring**: Watch others' terminal sessions in real-time
+
+### How It Works
+
+```
+┌──────────┐     ┌─────────────────────────────────────────┐     ┌──────────┐
+│ Client A │◄────┤           SessionManager                 ├────►│   PTY    │
+└──────────┘     │  ┌─────────────────────────────────────┐ │     │ Process  │
+                 │  │         SharedSession                │ │     └──────────┘
+┌──────────┐     │  │  - clients: [A, B, C]               │ │
+│ Client B │◄────┼──┤  - historyBuffer (50KB)             │ │
+└──────────┘     │  │  - orphanedAt: null                 │ │
+                 │  └─────────────────────────────────────┘ │
+┌──────────┐     │                                         │
+│ Client C │◄────┼─────────────────────────────────────────┘
+└──────────┘              (broadcast output)
+```
+
+### Server Configuration
+
+```javascript
+const server = new TerminalServer({
+  // Maximum clients that can join a single session
+  maxClientsPerSession: 10,
+
+  // Time before orphaned session is killed (ms)
+  // Set to 0 to kill immediately on last client disconnect
+  orphanTimeout: 60000,
+
+  // History buffer size for replay on join
+  historySize: 50000,
+
+  // Enable/disable history feature
+  historyEnabled: true,
+
+  // Maximum total sessions across all clients
+  maxSessionsTotal: 100,
+});
+
+// Get session statistics
+const stats = server.getStats();
+// { sessionCount: 5, clientCount: 12, orphanedCount: 1 }
+
+// List all sessions with multiplexing info
+const sessions = server.getSharedSessions();
+```
+
+### Client API
+
+```javascript
+// List available sessions
+const sessions = await client.listSessions();
+// Filter by type or container
+const dockerSessions = await client.listSessions({ type: 'docker-exec' });
+
+// Create a shareable session
+await client.spawn({
+  shell: '/bin/bash',
+  label: 'dev-session',      // Optional label for identification
+  allowJoin: true,           // Allow others to join (default: true)
+  enableHistory: true,       // Enable history buffer (default: true)
+});
+
+// Join an existing session
+const session = await client.join({
+  sessionId: 'term-abc123...',
+  requestHistory: true,      // Request output history
+  historyLimit: 50000,       // Max history chars to receive
+});
+// session.history contains recent output
+
+// Leave session without killing it
+client.leave();
+// Session survives if other clients connected
+// Or waits orphanTimeout before closing
+
+// Kill session (only owner can do this)
+client.kill();
+```
+
+### Spawn Options for Multiplexing
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `label` | string | - | Session label for identification |
+| `allowJoin` | boolean | `true` | Allow other clients to join |
+| `enableHistory` | boolean | `true` | Enable history buffer |
+| `attachMode` | boolean | `false` | Use docker attach instead of exec |
+
+### Event Handlers
+
+```javascript
+// Called when another client joins your session
+client.onClientJoined((sessionId, clientCount) => {
+  console.log(`Client joined, ${clientCount} total`);
+});
+
+// Called when another client leaves
+client.onClientLeft((sessionId, clientCount) => {
+  console.log(`Client left, ${clientCount} remaining`);
+});
+
+// Called when session is closed
+client.onSessionClosed((sessionId, reason) => {
+  // reason: 'orphan_timeout' | 'owner_closed' | 'process_exit' | 'error'
+  console.log(`Session closed: ${reason}`);
+});
+```
+
+### Use Cases
+
+**1. Pair Programming**
+```javascript
+// Developer A creates session
+await client.spawn({ label: 'pair-session' });
+// Share session ID with Developer B
+// Developer B joins with history
+await client.join({ sessionId, requestHistory: true });
+```
+
+**2. Session Persistence**
+```javascript
+// Start long-running task
+await client.spawn({ shell: '/bin/bash' });
+client.write('npm run build\n');
+client.disconnect(); // Session survives!
+
+// Later, reconnect
+await client.connect();
+const sessions = await client.listSessions();
+await client.join({ sessionId: sessions[0].sessionId, requestHistory: true });
+// See build output that happened while disconnected
+```
+
+**3. Monitoring**
+```javascript
+// Admin joins session in read-only mode
+await client.join({ sessionId, requestHistory: true });
+// Watch activity without interfering
+```
+
 ## Security
 
 **Always configure security for production:**
@@ -461,6 +727,30 @@ const server = new TerminalServer({
 See the [examples](./examples) directory for complete working examples:
 
 - [**docker-container**](./examples/docker-container) - Connect to Docker containers from the browser
+- [**multiplexing**](./examples/multiplexing) - Session multiplexing with multiple clients sharing terminals
+
+### Running Locally (Development)
+
+```bash
+# Clone the repository
+git clone https://github.com/lsadehaan/x-shell.git
+cd x-shell
+
+# Install dependencies (including node-pty)
+npm install
+npm install node-pty --save-dev --legacy-peer-deps
+
+# Build the project
+npm run build
+
+# Start a test container (optional, for Docker exec testing)
+docker run -d --name test-container alpine sleep infinity
+
+# Run the example server
+node examples/docker-container/server.js
+
+# Open http://localhost:3000 in your browser
+```
 
 ### Quick Start with Docker Compose
 

package/dist/client/browser-bundle.js

@@ -17,9 +17,19 @@ var TerminalClient = class {
     this.spawnedHandlers = [];
     this.serverInfoHandlers = [];
     this.containerListHandlers = [];
-    // Promise resolvers for spawn
+    // Session multiplexing handlers
+    this.sessionListHandlers = [];
+    this.joinedHandlers = [];
+    this.leftHandlers = [];
+    this.clientJoinedHandlers = [];
+    this.clientLeftHandlers = [];
+    this.sessionClosedHandlers = [];
+    // Promise resolvers for spawn/join
     this.spawnResolve = null;
     this.spawnReject = null;
+    this.joinResolve = null;
+    this.joinReject = null;
+    this.listSessionsResolve = null;
     this.config = {
       url: config.url,
       reconnect: config.reconnect ?? true,
@@ -153,6 +163,11 @@ var TerminalClient = class {
           this.spawnResolve = null;
           this.spawnReject = null;
         }
+        if (this.joinReject) {
+          this.joinReject(error);
+          this.joinResolve = null;
+          this.joinReject = null;
+        }
         break;
       case "serverInfo":
         this.serverInfo = message.info;
@@ -161,6 +176,64 @@ var TerminalClient = class {
       case "containerList":
         this.containerListHandlers.forEach((handler) => handler(message.containers));
         break;
+      case "sessionList":
+        this.sessionListHandlers.forEach(
+          (handler) => handler(message.sessions)
+        );
+        if (this.listSessionsResolve) {
+          this.listSessionsResolve(message.sessions);
+          this.listSessionsResolve = null;
+        }
+        break;
+      case "joined":
+        const joinedSession = message.session;
+        const history = message.history;
+        this.sessionId = message.sessionId;
+        this.sessionInfo = {
+          sessionId: joinedSession.sessionId,
+          shell: joinedSession.shell,
+          cwd: joinedSession.cwd,
+          cols: joinedSession.cols,
+          rows: joinedSession.rows,
+          createdAt: joinedSession.createdAt,
+          container: joinedSession.container
+        };
+        this.joinedHandlers.forEach((handler) => handler(joinedSession, history));
+        if (this.joinResolve) {
+          this.joinResolve(joinedSession);
+          this.joinResolve = null;
+          this.joinReject = null;
+        }
+        break;
+      case "left":
+        const leftSessionId = message.sessionId;
+        if (this.sessionId === leftSessionId) {
+          this.sessionId = null;
+          this.sessionInfo = null;
+        }
+        this.leftHandlers.forEach((handler) => handler(leftSessionId));
+        break;
+      case "clientJoined":
+        this.clientJoinedHandlers.forEach(
+          (handler) => handler(message.sessionId, message.clientCount)
+        );
+        break;
+      case "clientLeft":
+        this.clientLeftHandlers.forEach(
+          (handler) => handler(message.sessionId, message.clientCount)
+        );
+        break;
+      case "sessionClosed":
+        const closedSessionId = message.sessionId;
+        const reason = message.reason;
+        if (this.sessionId === closedSessionId) {
+          this.sessionId = null;
+          this.sessionInfo = null;
+        }
+        this.sessionClosedHandlers.forEach(
+          (handler) => handler(closedSessionId, reason)
+        );
+        break;
     }
   }
   /**
@@ -173,7 +246,7 @@ var TerminalClient = class {
         return;
       }
       if (this.sessionId) {
-        reject(new Error("Session already spawned. Call kill() first."));
+        reject(new Error("Session already active. Call kill() or leave() first."));
         return;
       }
       this.spawnResolve = resolve;
@@ -228,7 +301,7 @@ var TerminalClient = class {
     );
   }
   /**
-   * Kill the terminal session
+   * Kill the terminal session (close and terminate)
    */
   kill() {
     if (!this.ws || this.state !== "connected") {
@@ -247,6 +320,91 @@ var TerminalClient = class {
     this.sessionInfo = null;
   }
   // ==========================================
+  // Session Multiplexing Methods
+  // ==========================================
+  /**
+   * List available sessions
+   */
+  listSessions(filter) {
+    return new Promise((resolve, reject) => {
+      if (this.state !== "connected" || !this.ws) {
+        reject(new Error("Not connected to server"));
+        return;
+      }
+      this.listSessionsResolve = resolve;
+      this.ws.send(
+        JSON.stringify({
+          type: "listSessions",
+          filter
+        })
+      );
+    });
+  }
+  /**
+   * Join an existing session
+   */
+  join(options) {
+    return new Promise((resolve, reject) => {
+      if (this.state !== "connected" || !this.ws) {
+        reject(new Error("Not connected to server"));
+        return;
+      }
+      if (this.sessionId) {
+        reject(new Error("Already in a session. Call leave() first."));
+        return;
+      }
+      this.joinResolve = resolve;
+      this.joinReject = reject;
+      this.ws.send(
+        JSON.stringify({
+          type: "join",
+          options
+        })
+      );
+    });
+  }
+  /**
+   * Leave the current session without killing it
+   */
+  leave(sessionId) {
+    if (!this.ws || this.state !== "connected") {
+      console.error("[x-shell] Cannot leave: not connected");
+      return;
+    }
+    const targetSession = sessionId || this.sessionId;
+    if (!targetSession) {
+      console.error("[x-shell] Cannot leave: no active session");
+      return;
+    }
+    this.ws.send(
+      JSON.stringify({
+        type: "leave",
+        sessionId: targetSession
+      })
+    );
+    if (targetSession === this.sessionId) {
+      this.sessionId = null;
+      this.sessionInfo = null;
+    }
+  }
+  /**
+   * Request session list and trigger onSessionList handlers
+   * (Fire-and-forget version of listSessions)
+   */
+  requestSessionList(filter) {
+    this.listSessions(filter).then((sessions) => {
+      this.sessionListHandlers.forEach((handler) => {
+        try {
+          handler(sessions);
+        } catch (e) {
+          console.error("[x-shell] Error in sessionList handler:", e);
+        }
+      });
+    }).catch((err) => {
+      console.error("[x-shell] Failed to list sessions:", err);
+    });
+  }
+  // ==========================================
   // Event handlers
   // ==========================================
   /**
@@ -300,6 +458,42 @@ var TerminalClient = class {
   onContainerList(handler) {
     this.containerListHandlers.push(handler);
   }
+  /**
+   * Called when session list is received
+   */
+  onSessionList(handler) {
+    this.sessionListHandlers.push(handler);
+  }
+  /**
+   * Called when successfully joined a session
+   */
+  onJoined(handler) {
+    this.joinedHandlers.push(handler);
+  }
+  /**
+   * Called when left a session
+   */
+  onLeft(handler) {
+    this.leftHandlers.push(handler);
+  }
+  /**
+   * Called when another client joins the current session
+   */
+  onClientJoined(handler) {
+    this.clientJoinedHandlers.push(handler);
+  }
+  /**
+   * Called when another client leaves the current session
+   */
+  onClientLeft(handler) {
+    this.clientLeftHandlers.push(handler);
+  }
+  /**
+   * Called when the session is closed by owner or orphan timeout
+   */
+  onSessionClosed(handler) {
+    this.sessionClosedHandlers.push(handler);
+  }
   /**
    * Request list of available containers
    */