lit-shell.js 0.1.3 → 1.1.0

package/README.md

@@ -1,304 +1,304 @@
-# lit-shell.js
-
-> WebSocket-based terminal for Node.js - the truth is in your shell
-
-A plug-and-play terminal solution for web applications. Includes a server component (node-pty), client library, and ready-to-use Lit web component.
-
-## Features
-
-- **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
-- **Themes**: Built-in dark/light/auto theme support
-- **Security**: Configurable shell and path allowlists
-- **Framework Agnostic**: Works with React, Vue, Angular, Svelte, or vanilla JS
-
-## Installation
-
-```bash
-npm install lit-shell.js node-pty
-```
-
-Note: `node-pty` requires native compilation. See [node-pty docs](https://github.com/microsoft/node-pty) for platform-specific requirements.
-
-## Quick Start
-
-### Server Setup
-
-```javascript
-import express from 'express';
-import { createServer } from 'http';
-import { TerminalServer } from 'lit-shell.js/server';
-
-const app = express();
-const server = createServer(app);
-
-// Create and attach terminal server
-const terminalServer = new TerminalServer({
-  allowedShells: ['/bin/bash', '/bin/zsh'],
-  allowedPaths: ['/home/user'],
-  defaultCwd: '/home/user',
-  verbose: true,
-});
-
-terminalServer.attach(server);
-
-server.listen(3000, () => {
-  console.log('Server running on http://localhost: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 -->
-<script type="module" src="https://unpkg.com/lit-shell.js/dist/ui/browser-bundle.js"></script>
-
-<!-- Use the component -->
-<lit-shell-terminal
-  url="ws://localhost:3000/terminal"
-  theme="dark"
-  auto-connect
-  auto-spawn
-></lit-shell-terminal>
-```
-
-### Client Usage (JavaScript)
-
-```javascript
-import { TerminalClient } from 'lit-shell.js/client';
-
-const client = new TerminalClient({
-  url: 'ws://localhost:3000/terminal'
-});
-
-await client.connect();
-
-client.onData((data) => {
-  console.log('Output:', data);
-});
-
-client.onExit((code) => {
-  console.log('Exited with code:', code);
-});
-
-await client.spawn({
-  shell: '/bin/bash',
-  cwd: '/home/user'
-});
-
-client.write('ls -la\n');
-client.resize(120, 40);
-```
-
-## API Reference
-
-### Server
-
-#### `TerminalServer`
-
-```typescript
-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
-  defaultShell: '/bin/bash',
-
-  // Default working directory
-  defaultCwd: '/home/user',
-
-  // Max sessions per client (default: 5)
-  maxSessionsPerClient: 5,
-
-  // Idle timeout in ms (default: 30 minutes, 0 = disabled)
-  idleTimeout: 30 * 60 * 1000,
-
-  // WebSocket path (default: '/terminal')
-  path: '/terminal',
-
-  // Enable verbose logging
-  verbose: false,
-});
-
-// Attach to HTTP server
-server.attach(httpServer);
-
-// Or start standalone
-server.listen(3001);
-
-// Get active sessions
-const sessions = server.getSessions();
-
-// Close server
-server.close();
-```
-
-### Client
-
-#### `TerminalClient`
-
-```typescript
-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)
-});
-
-// Connect to server
-await client.connect();
-
-// Spawn terminal session
-const sessionInfo = await client.spawn({
-  shell: '/bin/bash',
-  cwd: '/home/user',
-  env: { TERM: 'xterm-256color' },
-  cols: 80,
-  rows: 24,
-});
-
-// Write to terminal
-client.write('echo "Hello World"\n');
-
-// Resize terminal
-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
-```
-
-### UI Component
-
-#### `<lit-shell-terminal>`
-
-```html
-<lit-shell-terminal
-  url="ws://localhost:3000/terminal"
-  shell="/bin/bash"
-  cwd="/home/user"
-  theme="dark"
-  font-size="14"
-  font-family="Menlo, Monaco, monospace"
-  cols="80"
-  rows="24"
-  auto-connect
-  auto-spawn
-  no-header
-></lit-shell-terminal>
-```
-
-**Attributes:**
-
-| Attribute | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `url` | string | `''` | WebSocket URL |
-| `shell` | string | `''` | Shell to use |
-| `cwd` | string | `''` | Working directory |
-| `theme` | `'dark'` \| `'light'` \| `'auto'` | `'dark'` | Color theme |
-| `font-size` | number | `14` | Terminal font size |
-| `font-family` | string | `'Menlo, Monaco, ...'` | 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 |
-
-**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
-```
-
-**Events:**
-
-```javascript
-terminal.addEventListener('connect', () => {});
-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));
-```
-
-## Theming
-
-The component uses CSS custom properties for theming:
-
-```css
-lit-shell-terminal {
-  --ls-bg: #1e1e1e;
-  --ls-bg-header: #2d2d2d;
-  --ls-text: #cccccc;
-  --ls-text-muted: #808080;
-  --ls-border: #3e3e3e;
-  --ls-terminal-bg: #1e1e1e;
-  --ls-terminal-fg: #cccccc;
-  --ls-terminal-cursor: #ffffff;
-  --ls-terminal-selection: #264f78;
-  --ls-btn-bg: #3c3c3c;
-  --ls-btn-text: #cccccc;
-  --ls-btn-hover: #4a4a4a;
-  --ls-status-connected: #22c55e;
-  --ls-status-disconnected: #ef4444;
-}
-```
-
-## Security
-
-**Always configure security for production:**
-
-```javascript
-const server = new TerminalServer({
-  // Restrict allowed shells
-  allowedShells: ['/bin/bash'],
-
-  // Restrict working directories
-  allowedPaths: ['/home/app', '/var/www'],
-
-  // Limit sessions per client
-  maxSessionsPerClient: 2,
-
-  // Set idle timeout
-  idleTimeout: 10 * 60 * 1000, // 10 minutes
-});
-```
-
-## License
-
-MIT
+# lit-shell.js
+
+> WebSocket-based terminal for Node.js - the truth is in your shell
+
+A plug-and-play terminal solution for web applications. Includes a server component (node-pty), client library, and ready-to-use Lit web component.
+
+## Features
+
+- **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
+- **Themes**: Built-in dark/light/auto theme support
+- **Security**: Configurable shell and path allowlists
+- **Framework Agnostic**: Works with React, Vue, Angular, Svelte, or vanilla JS
+
+## Installation
+
+```bash
+npm install lit-shell.js node-pty
+```
+
+Note: `node-pty` requires native compilation. See [node-pty docs](https://github.com/microsoft/node-pty) for platform-specific requirements.
+
+## Quick Start
+
+### Server Setup
+
+```javascript
+import express from 'express';
+import { createServer } from 'http';
+import { TerminalServer } from 'lit-shell.js/server';
+
+const app = express();
+const server = createServer(app);
+
+// Create and attach terminal server
+const terminalServer = new TerminalServer({
+  allowedShells: ['/bin/bash', '/bin/zsh'],
+  allowedPaths: ['/home/user'],
+  defaultCwd: '/home/user',
+  verbose: true,
+});
+
+terminalServer.attach(server);
+
+server.listen(3000, () => {
+  console.log('Server running on http://localhost: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 -->
+<script type="module" src="https://unpkg.com/lit-shell.js/dist/ui/browser-bundle.js"></script>
+
+<!-- Use the component -->
+<lit-shell-terminal
+  url="ws://localhost:3000/terminal"
+  theme="dark"
+  auto-connect
+  auto-spawn
+></lit-shell-terminal>
+```
+
+### Client Usage (JavaScript)
+
+```javascript
+import { TerminalClient } from 'lit-shell.js/client';
+
+const client = new TerminalClient({
+  url: 'ws://localhost:3000/terminal'
+});
+
+await client.connect();
+
+client.onData((data) => {
+  console.log('Output:', data);
+});
+
+client.onExit((code) => {
+  console.log('Exited with code:', code);
+});
+
+await client.spawn({
+  shell: '/bin/bash',
+  cwd: '/home/user'
+});
+
+client.write('ls -la\n');
+client.resize(120, 40);
+```
+
+## API Reference
+
+### Server
+
+#### `TerminalServer`
+
+```typescript
+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
+  defaultShell: '/bin/bash',
+
+  // Default working directory
+  defaultCwd: '/home/user',
+
+  // Max sessions per client (default: 5)
+  maxSessionsPerClient: 5,
+
+  // Idle timeout in ms (default: 30 minutes, 0 = disabled)
+  idleTimeout: 30 * 60 * 1000,
+
+  // WebSocket path (default: '/terminal')
+  path: '/terminal',
+
+  // Enable verbose logging
+  verbose: false,
+});
+
+// Attach to HTTP server
+server.attach(httpServer);
+
+// Or start standalone
+server.listen(3001);
+
+// Get active sessions
+const sessions = server.getSessions();
+
+// Close server
+server.close();
+```
+
+### Client
+
+#### `TerminalClient`
+
+```typescript
+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)
+});
+
+// Connect to server
+await client.connect();
+
+// Spawn terminal session
+const sessionInfo = await client.spawn({
+  shell: '/bin/bash',
+  cwd: '/home/user',
+  env: { TERM: 'xterm-256color' },
+  cols: 80,
+  rows: 24,
+});
+
+// Write to terminal
+client.write('echo "Hello World"\n');
+
+// Resize terminal
+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
+```
+
+### UI Component
+
+#### `<lit-shell-terminal>`
+
+```html
+<lit-shell-terminal
+  url="ws://localhost:3000/terminal"
+  shell="/bin/bash"
+  cwd="/home/user"
+  theme="dark"
+  font-size="14"
+  font-family="Menlo, Monaco, monospace"
+  cols="80"
+  rows="24"
+  auto-connect
+  auto-spawn
+  no-header
+></lit-shell-terminal>
+```
+
+**Attributes:**
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | string | `''` | WebSocket URL |
+| `shell` | string | `''` | Shell to use |
+| `cwd` | string | `''` | Working directory |
+| `theme` | `'dark'` \| `'light'` \| `'auto'` | `'dark'` | Color theme |
+| `font-size` | number | `14` | Terminal font size |
+| `font-family` | string | `'Menlo, Monaco, ...'` | 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 |
+
+**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
+```
+
+**Events:**
+
+```javascript
+terminal.addEventListener('connect', () => {});
+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));
+```
+
+## Theming
+
+The component uses CSS custom properties for theming:
+
+```css
+lit-shell-terminal {
+  --ls-bg: #1e1e1e;
+  --ls-bg-header: #2d2d2d;
+  --ls-text: #cccccc;
+  --ls-text-muted: #808080;
+  --ls-border: #3e3e3e;
+  --ls-terminal-bg: #1e1e1e;
+  --ls-terminal-fg: #cccccc;
+  --ls-terminal-cursor: #ffffff;
+  --ls-terminal-selection: #264f78;
+  --ls-btn-bg: #3c3c3c;
+  --ls-btn-text: #cccccc;
+  --ls-btn-hover: #4a4a4a;
+  --ls-status-connected: #22c55e;
+  --ls-status-disconnected: #ef4444;
+}
+```
+
+## Security
+
+**Always configure security for production:**
+
+```javascript
+const server = new TerminalServer({
+  // Restrict allowed shells
+  allowedShells: ['/bin/bash'],
+
+  // Restrict working directories
+  allowedPaths: ['/home/app', '/var/www'],
+
+  // Limit sessions per client
+  maxSessionsPerClient: 2,
+
+  // Set idle timeout
+  idleTimeout: 10 * 60 * 1000, // 10 minutes
+});
+```
+
+## License
+
+MIT