TERMINAL_README.md

# 🚀 Manus AI-Style Terminal Integration

This document explains the real-time terminal streaming functionality added to the Data Extractor application.

## 📋 Overview

The terminal integration provides a **Manus AI-style terminal interface** with real-time command execution and streaming output, seamlessly integrated into the existing Gradio application.

## 🏗️ Architecture

### Components

1. **WebSocket Server** (`terminal_stream.py`)
   - Handles real-time communication between frontend and backend
   - Manages command execution with streaming output
   - Supports multiple concurrent connections
   - Runs on port 8765

2. **Frontend Terminal** (`static/terminal.html`)
   - Beautiful Manus AI-inspired terminal interface
   - Real-time output streaming via WebSocket
   - Command history navigation
   - Keyboard shortcuts and controls

3. **Gradio Integration** (Modified `app.py`)
   - Added terminal tab to existing interface
   - Embedded terminal as iframe component
   - Auto-starts WebSocket server on application launch

## 🎨 Features

### Terminal Interface
- **Real-time Streaming**: Live command output as it happens
- **Command History**: Navigate with ↑/↓ arrow keys
- **Interrupt Support**: Ctrl+C to stop running commands
- **Auto-reconnect**: Automatically reconnects on connection loss
- **Status Indicators**: Visual connection and execution status
- **Responsive Design**: Works on desktop and mobile

### Security
- **Command Sanitization**: Uses `shlex.split()` for safe command parsing
- **Process Isolation**: Commands run in separate processes
- **Error Handling**: Robust error handling and logging

## 🚀 Usage

### Starting the Application
```bash
python app.py
```

The terminal WebSocket server automatically starts on port 8765.

### Accessing the Terminal
1. Open the Gradio interface (usually http://localhost:7860)
2. Click on the "💻 Terminal" tab
3. Start typing commands in the terminal interface

### Keyboard Shortcuts
- **Enter**: Execute command
- **↑/↓**: Navigate command history
- **Ctrl+C**: Interrupt running command
- **Ctrl+L**: Clear terminal screen
- **Tab**: Command completion (planned feature)

## 🔧 Configuration

### WebSocket Server Settings
```python
# In terminal_stream.py
WEBSOCKET_HOST = 'localhost'
WEBSOCKET_PORT = 8765
```

### Terminal Appearance
Customize the terminal appearance by modifying the CSS in `static/terminal.html`:

```css
/* Main terminal colors */
.terminal-container {
    background: linear-gradient(135deg, #0d1117 0%, #161b22 100%);
}

/* Command prompt */
.prompt {
    color: #58a6ff;
}
```

## 📡 WebSocket API

### Client → Server Messages

#### Execute Command
```json
{
    "type": "command",
    "command": "ls -la"
}
```

#### Interrupt Command
```json
{
    "type": "interrupt"
}
```

### Server → Client Messages

#### Command Output
```json
{
    "type": "output",
    "data": "file1.txt\nfile2.txt",
    "stream": "stdout",
    "timestamp": "2024-01-01T12:00:00.000Z"
}
```

#### Command Completion
```json
{
    "type": "command_complete",
    "exit_code": 0,
    "message": "Process exited with code 0",
    "timestamp": "2024-01-01T12:00:00.000Z"
}
```

## 🛠️ Development

### Adding New Features

1. **Server-side**: Modify `terminal_stream.py`
2. **Client-side**: Update `static/terminal.html`
3. **Integration**: Adjust `app.py` if needed

### Testing

```bash
# Test WebSocket server independently
python -c "from terminal_stream import run_websocket_server; run_websocket_server()"

# Test terminal interface
# Open static/terminal.html in browser
```

## 🔍 Troubleshooting

### Common Issues

1. **WebSocket Connection Failed**
   - Check if port 8765 is available
   - Verify firewall settings
   - Check server logs for errors

2. **Commands Not Executing**
   - Verify WebSocket connection status
   - Check terminal logs for errors
   - Ensure proper command syntax

3. **Terminal Not Loading**
   - Check if `static/terminal.html` exists
   - Verify Gradio file serving configuration
   - Check browser console for errors

### Debug Mode

Enable debug logging:
```python
import logging
logging.getLogger('terminal_stream').setLevel(logging.DEBUG)
```

## 🚀 Advanced Usage

### Custom Commands

Add custom command handlers in `terminal_stream.py`:

```python
async def handle_custom_command(self, command):
    if command.startswith('custom:'):
        # Handle custom command
        await self.broadcast({
            'type': 'output',
            'data': 'Custom command executed',
            'stream': 'stdout'
        })
        return True
    return False
```

### Integration with Workflow

Stream workflow logs to terminal:

```python
# In workflow code
from terminal_stream import terminal_manager

async def log_to_terminal(message):
    await terminal_manager.broadcast({
        'type': 'output',
        'data': message,
        'stream': 'workflow'
    })
```

## 📚 Dependencies

- `websockets`: WebSocket server implementation
- `asyncio`: Async programming support
- `subprocess`: Command execution
- `shlex`: Safe command parsing

## 🎯 Future Enhancements

- [ ] Command auto-completion
- [ ] File upload/download via terminal
- [ ] Terminal themes and customization
- [ ] Multi-session support
- [ ] Terminal recording and playback
- [ ] Integration with workflow logging
- [ ] SSH/remote terminal support

## 📄 License

This terminal implementation is part of the Data Extractor project and follows the same license terms.