lit-shell.js 0.1.4 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# 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.2.0] - 2025-02-01
+
+### Added
+
+- **Mobile Support**: Auto-detect mobile devices and show touch keyboard
+  - Termux-style layout: ESC, arrows, HOME/END, PGUP/PGDN, TAB
+  - Sticky CTRL and ALT modifiers
+  - Collapsible extra row with common control sequences (^C, ^D, ^Z, ^L, ^A, ^E, ^R)
+  - Hide/show toggle for entire keyboard
+  - Responsive viewport detection with media query listener
+- **Reconnect Dialog**: After WebSocket reconnection, shows dialog to rejoin previous session
+  - Saves session ID on disconnect
+  - Checks if session still exists after reconnect
+  - Option to rejoin with history or start fresh
+- **Session Persistence Options**: Connection panel now includes
+  - Configurable orphan timeout (1 min to 1 week)
+  - Tmux integration checkbox for permanent persistence
+- **Updated Font Stack**: Terminal now uses Cascadia Mono as primary font for better cross-platform consistency
+
+### Changed
+
+- Improved README documentation with all new features
+- Updated feature list to include Docker, multiplexing, mobile, and persistence
+
+## [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
+- `<lit-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,8 +9,13 @@ 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**: `<lit-shell-terminal>` Lit web component with xterm.js
+- **Docker Support**: Execute commands in Docker containers (exec or attach mode)
+- **Session Multiplexing**: Multiple clients can share the same terminal session
+- **Session Persistence**: Orphan timeout and tmux integration for long-running sessions
+- **Mobile Support**: Touch keyboard with Termux-style layout for mobile devices
+- **Multi-Tab**: Support for multiple terminal tabs in one component
 - **Themes**: Built-in dark/light/auto theme support
-- **Security**: Configurable shell and path allowlists
+- **Security**: Configurable shell, path, and container allowlists
 - **Framework Agnostic**: Works with React, Vue, Angular, Svelte, or vanilla JS
 
 ## Installation
@@ -51,10 +56,7 @@ server.listen(3000, () => {
 ### Client Usage (Web Component)
 
 ```html
-<!-- Load xterm.js CSS -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/xterm@5.3.0/css/xterm.css">
-
-<!-- Load lit-shell.js UI bundle -->
+<!-- Load lit-shell.js UI bundle (includes xterm.js) -->
 <script type="module" src="https://unpkg.com/lit-shell.js/dist/ui/browser-bundle.js"></script>
 
 <!-- Use the component -->
@@ -94,6 +96,97 @@ client.write('ls -la\n');
 client.resize(120, 40);
 ```
 
+## Docker Support
+
+lit-shell supports executing commands inside Docker containers via two modes:
+
+### Docker Exec Mode
+
+Spawns a new shell inside a running container:
+
+```javascript
+const terminalServer = new TerminalServer({
+  allowDockerExec: true,
+  allowedContainerPatterns: ['my-app-.*', 'dev-container'],
+  defaultContainerShell: '/bin/bash',
+});
+
+// Client-side
+await client.spawn({
+  container: 'my-container',
+  containerShell: '/bin/bash',
+  containerUser: 'node',
+  containerCwd: '/app',
+});
+```
+
+### Docker Attach Mode
+
+Attaches to a container's main process (stdin/stdout):
+
+```javascript
+await client.spawn({
+  container: 'my-container',
+  attachMode: true,
+});
+```
+
+## Session Multiplexing
+
+Multiple clients can share the same terminal session:
+
+```javascript
+// First client spawns a session
+const session = await client1.spawn({ shell: '/bin/bash' });
+
+// Second client joins the same session
+const shared = await client2.join({
+  sessionId: session.sessionId,
+  requestHistory: true,  // Replay terminal history
+  historyLimit: 10000,
+});
+
+// Both clients now see the same terminal
+// Either can type, both see the output
+```
+
+### Session List
+
+```javascript
+// Get available sessions
+client.onSessionList((sessions) => {
+  sessions.forEach(s => {
+    console.log(`${s.sessionId}: ${s.shell} (${s.clientCount} clients)`);
+  });
+});
+
+client.requestSessionList();
+```
+
+## Session Persistence
+
+### Orphan Timeout
+
+Sessions can persist after all clients disconnect:
+
+```javascript
+await client.spawn({
+  shell: '/bin/bash',
+  orphanTimeout: 3600000,  // Keep alive 1 hour after last client leaves
+});
+```
+
+### Tmux Integration
+
+For permanent session persistence:
+
+```javascript
+await client.spawn({
+  shell: '/bin/bash',
+  useTmux: true,  // Session persists indefinitely in tmux
+});
+```
+
 ## API Reference
 
 ### Server
@@ -104,28 +197,31 @@ client.resize(120, 40);
 import { TerminalServer } from 'lit-shell.js/server';
 
 const server = new TerminalServer({
-  // Allowed shells (empty = all allowed)
-  allowedShells: ['/bin/bash', '/bin/zsh', 'cmd.exe'],
-
-  // Allowed working directories (empty = all allowed)
-  allowedPaths: ['/home/user', '/var/www'],
-
-  // Default shell if not specified
+  // Shell configuration
+  allowedShells: ['/bin/bash', '/bin/zsh'],
   defaultShell: '/bin/bash',
 
-  // Default working directory
+  // Path restrictions
+  allowedPaths: ['/home/user', '/var/www'],
   defaultCwd: '/home/user',
 
-  // Max sessions per client (default: 5)
-  maxSessionsPerClient: 5,
+  // Docker configuration
+  allowDockerExec: false,
+  allowedContainerPatterns: ['.*'],
+  defaultContainerShell: '/bin/sh',
 
-  // Idle timeout in ms (default: 30 minutes, 0 = disabled)
+  // Session limits
+  maxSessionsPerClient: 5,
   idleTimeout: 30 * 60 * 1000,
 
-  // WebSocket path (default: '/terminal')
+  // History
+  historyEnabled: true,
+  historySize: 50000,
+
+  // WebSocket path
   path: '/terminal',
 
-  // Enable verbose logging
+  // Logging
   verbose: false,
 });
 
@@ -134,12 +230,6 @@ server.attach(httpServer);
 
 // Or start standalone
 server.listen(3001);
-
-// Get active sessions
-const sessions = server.getSessions();
-
-// Close server
-server.close();
 ```
 
 ### Client
@@ -151,48 +241,52 @@ import { TerminalClient } from 'lit-shell.js/client';
 
 const client = new TerminalClient({
   url: 'ws://localhost:3000/terminal',
-  reconnect: true,           // Auto-reconnect (default: true)
-  maxReconnectAttempts: 10,  // Max attempts (default: 10)
-  reconnectDelay: 1000,      // Initial delay ms (default: 1000)
+  reconnect: true,
+  maxReconnectAttempts: 10,
+  reconnectDelay: 1000,
 });
 
-// Connect to server
+// Connect
 await client.connect();
 
-// Spawn terminal session
-const sessionInfo = await client.spawn({
+// Spawn session
+const session = await client.spawn({
   shell: '/bin/bash',
   cwd: '/home/user',
   env: { TERM: 'xterm-256color' },
   cols: 80,
   rows: 24,
+  container: 'optional-container-name',
+  orphanTimeout: 3600000,
+  useTmux: false,
+});
+
+// Join existing session
+const shared = await client.join({
+  sessionId: 'session-id',
+  requestHistory: true,
+  historyLimit: 50000,
 });
 
-// Write to terminal
-client.write('echo "Hello World"\n');
+// Leave session (without killing it)
+client.leave(sessionId);
 
-// Resize terminal
+// Terminal I/O
+client.write('echo "Hello"\n');
 client.resize(120, 40);
-
-// Kill session
 client.kill();
 
-// Disconnect
-client.disconnect();
-
 // Event handlers
-client.onConnect(() => console.log('Connected'));
-client.onDisconnect(() => console.log('Disconnected'));
-client.onData((data) => console.log('Data:', data));
-client.onExit((code) => console.log('Exit:', code));
-client.onError((err) => console.log('Error:', err));
-client.onSpawned((info) => console.log('Spawned:', info));
-
-// State getters
-client.isConnected();      // boolean
-client.hasActiveSession(); // boolean
-client.getSessionId();     // string | null
-client.getSessionInfo();   // SessionInfo | null
+client.onConnect(() => {});
+client.onDisconnect(() => {});
+client.onData((data) => {});
+client.onExit((code) => {});
+client.onError((err) => {});
+client.onSpawned((info) => {});
+client.onSessionList((sessions) => {});
+client.onClientJoined((sessionId, count) => {});
+client.onClientLeft((sessionId, count) => {});
+client.onReconnectWithSession((sessionId) => {});
 ```
 
 ### UI Component
@@ -206,12 +300,14 @@ client.getSessionInfo();   // SessionInfo | null
   cwd="/home/user"
   theme="dark"
   font-size="14"
-  font-family="Menlo, Monaco, monospace"
   cols="80"
   rows="24"
   auto-connect
   auto-spawn
-  no-header
+  show-connection-panel
+  show-status-bar
+  show-tabs
+  show-settings
 ></lit-shell-terminal>
 ```
 
@@ -222,28 +318,40 @@ client.getSessionInfo();   // SessionInfo | null
 | `url` | string | `''` | WebSocket URL |
 | `shell` | string | `''` | Shell to use |
 | `cwd` | string | `''` | Working directory |
+| `container` | string | `''` | Docker container name |
 | `theme` | `'dark'` \| `'light'` \| `'auto'` | `'dark'` | Color theme |
 | `font-size` | number | `14` | Terminal font size |
-| `font-family` | string | `'Menlo, Monaco, ...'` | Terminal font |
+| `font-family` | string | `'Cascadia Mono, ...'` | Terminal font |
 | `cols` | number | `80` | Initial columns |
 | `rows` | number | `24` | Initial rows |
 | `auto-connect` | boolean | `false` | Connect on mount |
 | `auto-spawn` | boolean | `false` | Spawn on connect |
 | `no-header` | boolean | `false` | Hide header bar |
+| `show-connection-panel` | boolean | `false` | Show connection options |
+| `show-status-bar` | boolean | `false` | Show status bar |
+| `show-tabs` | boolean | `false` | Enable multi-tab mode |
+| `show-settings` | boolean | `false` | Show settings menu |
 
 **Methods:**
 
 ```javascript
 const terminal = document.querySelector('lit-shell-terminal');
 
-await terminal.connect();     // Connect to server
-terminal.disconnect();        // Disconnect
-await terminal.spawn();       // Spawn session
-terminal.kill();              // Kill session
-terminal.clear();             // Clear display
-terminal.write('text');       // Write to display
-terminal.writeln('line');     // Write line to display
-terminal.focus();             // Focus terminal
+await terminal.connect();
+terminal.disconnect();
+await terminal.spawn(options);
+await terminal.join(sessionId);
+terminal.leave();
+terminal.kill();
+terminal.clear();
+terminal.write('text');
+terminal.writeln('line');
+terminal.focus();
+
+// Tab management (when show-tabs is enabled)
+terminal.createTab('Label');
+terminal.switchTab(tabId);
+terminal.closeTab(tabId);
 ```
 
 **Events:**
@@ -254,8 +362,23 @@ terminal.addEventListener('disconnect', () => {});
 terminal.addEventListener('spawned', (e) => console.log(e.detail.session));
 terminal.addEventListener('exit', (e) => console.log(e.detail.exitCode));
 terminal.addEventListener('error', (e) => console.log(e.detail.error));
+terminal.addEventListener('theme-change', (e) => console.log(e.detail.theme));
+```
+
+## Mobile Support
+
+On mobile devices, lit-shell automatically shows a touch keyboard with common terminal keys:
+
+```
+Row 1: [ESC] [/] [-] [HOME] [↑] [END] [PGUP]
+Row 2: [TAB] [CTRL] [ALT] [←] [↓] [→] [PGDN]
+Row 3: [^C] [^D] [^Z] [^L] [^A] [^E] [^R]  (expandable)
 ```
 
+- CTRL and ALT are sticky modifiers (tap to activate, applies to next key)
+- Collapsible extra row for common control sequences
+- Hide/show toggle for the entire keyboard
+
 ## Theming
 
 The component uses CSS custom properties for theming:
@@ -291,11 +414,15 @@ const server = new TerminalServer({
   // Restrict working directories
   allowedPaths: ['/home/app', '/var/www'],
 
+  // Restrict Docker containers
+  allowDockerExec: true,
+  allowedContainerPatterns: ['^myapp-'],
+
   // Limit sessions per client
   maxSessionsPerClient: 2,
 
   // Set idle timeout
-  idleTimeout: 10 * 60 * 1000, // 10 minutes
+  idleTimeout: 10 * 60 * 1000,
 });
 ```