web-terminal-agent 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# web-terminal-agent
+
+A lightweight local agent that enables browser-based terminal access to your computer. Use CLI tools like Claude Code through a friendly web interface - no terminal experience required!
+
+## Quick Start
+
+```bash
+npx web-terminal-agent
+```
+
+That's it! The agent will start and you can connect from the web interface.
+
+## What is this?
+
+This agent runs on your computer and creates a secure bridge between your browser and your local terminal. It allows web applications to:
+
+- Execute shell commands on your machine
+- Run CLI tools like Claude Code, Clawdbot, etc.
+- Navigate your file system
+- Install development tools
+
+## Security
+
+**Your security is our priority:**
+
+- ✅ **Localhost only** - The agent only listens on `127.0.0.1` (your computer). It cannot be accessed from the internet or other devices.
+- ✅ **You're in control** - You start and stop the agent whenever you want. Just press `Ctrl+C` to stop.
+- ✅ **Transparent** - All commands are logged in your terminal so you can see exactly what's happening.
+- ✅ **Open source** - The code is fully visible and auditable.
+
+## Installation Options
+
+### Option 1: Run without installing (Recommended)
+
+```bash
+npx web-terminal-agent
+```
+
+### Option 2: Install globally
+
+```bash
+npm install -g web-terminal-agent
+web-terminal-agent
+```
+
+### Option 3: Clone and run
+
+```bash
+git clone https://github.com/user/web-terminal-agent.git
+cd web-terminal-agent
+npm install
+node index.js
+```
+
+## Configuration
+
+By default, the agent runs on port `3456`. You can change this:
+
+```bash
+PORT=8080 npx web-terminal-agent
+```
+
+## Requirements
+
+- Node.js 18 or higher
+- Works on Windows, macOS, and Linux
+
+## How it works
+
+1. You run the agent on your computer
+2. The agent starts a local server on `http://127.0.0.1:3456`
+3. The web interface connects to this local server
+4. Commands from the web interface are executed on your machine
+5. Output is streamed back to the web interface in real-time
+
+## API Endpoints
+
+If you want to integrate with the agent programmatically:
+
+- `GET /health` - Check if agent is running
+- `GET /cwd` - Get current working directory
+- `POST /execute` - Execute a command (body: `{ "command": "ls -la" }`)
+- `GET /tools/:tool` - Check if a tool is installed
+- `POST /tools/:tool/install` - Install a tool
+- `WebSocket /ws` - Real-time command execution
+
+## Troubleshooting
+
+### Port already in use
+
+If port 3456 is busy, use a different port:
+
+```bash
+PORT=3457 npx web-terminal-agent
+```
+
+### Permission denied
+
+On macOS/Linux, you might need to make the script executable:
+
+```bash
+chmod +x ./node_modules/.bin/web-terminal-agent
+```
+
+### Connection refused in browser
+
+Make sure:
+1. The agent is running (you should see the banner in your terminal)
+2. You're connecting to `http://localhost:3456` (not `127.0.0.1` in some browsers)
+3. No firewall is blocking localhost connections
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+
+/**
+ * Web Terminal Agent
+ * 
+ * A lightweight local server that enables browser-based terminal access.
+ * Runs on localhost only for security.
+ * 
+ * Usage: npx web-terminal-agent
+ *        node index.js
+ *        web-terminal-agent (if installed globally)
+ */
+
+const express = require('express');
+const cors = require('cors');
+const { WebSocketServer } = require('ws');
+const { spawn, exec } = require('child_process');
+const http = require('http');
+const os = require('os');
+const path = require('path');
+
+// Configuration
+const PORT = process.env.PORT || 3456;
+const HOST = '127.0.0.1'; // Only listen on localhost for security
+
+// ANSI color codes for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
+  dim: '\x1b[2m',
+};
+
+// Print banner
+function printBanner() {
+  console.log(`
+${colors.green}╔═══════════════════════════════════════════════════════════╗
+║                                                               ║
+║   ${colors.cyan}██╗    ██╗███████╗██████╗     ████████╗███████╗██████╗ ███╗   ███╗${colors.green}   ║
+║   ${colors.cyan}██║    ██║██╔════╝██╔══██╗    ╚══██╔══╝██╔════╝██╔══██╗████╗ ████║${colors.green}   ║
+║   ${colors.cyan}██║ █╗ ██║█████╗  ██████╔╝       ██║   █████╗  ██████╔╝██╔████╔██║${colors.green}   ║
+║   ${colors.cyan}██║███╗██║██╔══╝  ██╔══██╗       ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║${colors.green}   ║
+║   ${colors.cyan}╚███╔███╔╝███████╗██████╔╝       ██║   ███████╗██║  ██║██║ ╚═╝ ██║${colors.green}   ║
+║   ${colors.cyan} ╚══╝╚══╝ ╚══════╝╚═════╝        ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝${colors.green}   ║
+║                                                               ║
+║                    ${colors.yellow}LOCAL AGENT v1.0.0${colors.green}                         ║
+║                                                               ║
+╚═══════════════════════════════════════════════════════════════╝${colors.reset}
+`);
+}
+
+// Get current working directory display
+let currentDir = process.cwd();
+
+function getShortDir(dir) {
+  const home = os.homedir();
+  if (dir.startsWith(home)) {
+    return '~' + dir.slice(home.length);
+  }
+  return dir;
+}
+
+// Detect platform
+const isWindows = process.platform === 'win32';
+const shell = isWindows ? 'cmd.exe' : (process.env.SHELL || '/bin/bash');
+const shellArgs = isWindows ? ['/c'] : ['-c'];
+
+// Check if a command/tool is installed
+async function checkToolInstalled(command) {
+  return new Promise((resolve) => {
+    const checkCmd = isWindows ? 'where' : 'which';
+    exec(`${checkCmd} ${command}`, (error) => {
+      resolve(!error);
+    });
+  });
+}
+
+// Get tool version
+async function getToolVersion(command) {
+  return new Promise((resolve) => {
+    exec(`${command} --version`, (error, stdout) => {
+      if (error) {
+        resolve(null);
+      } else {
+        resolve(stdout.trim().split('\n')[0]);
+      }
+    });
+  });
+}
+
+// Install a tool
+async function installTool(tool, ws) {
+  const installCommands = {
+    'claude-code': 'npm install -g @anthropic-ai/claude-code',
+    'clawdbot': 'npm install -g clawdbot',
+  };
+
+  const cmd = installCommands[tool];
+  if (!cmd) {
+    return { success: false, error: 'Unknown tool' };
+  }
+
+  return new Promise((resolve) => {
+    const proc = spawn(shell, [...shellArgs, cmd], {
+      cwd: currentDir,
+      env: process.env,
+    });
+
+    proc.stdout.on('data', (data) => {
+      if (ws && ws.readyState === 1) {
+        ws.send(JSON.stringify({ type: 'output', content: data.toString() }));
+      }
+    });
+
+    proc.stderr.on('data', (data) => {
+      if (ws && ws.readyState === 1) {
+        ws.send(JSON.stringify({ type: 'output', content: data.toString() }));
+      }
+    });
+
+    proc.on('close', (code) => {
+      resolve({ success: code === 0 });
+    });
+  });
+}
+
+// Execute a command
+function executeCommand(command, ws) {
+  return new Promise((resolve) => {
+    // Handle cd command specially
+    if (command.trim().startsWith('cd ')) {
+      const newDir = command.trim().slice(3).trim();
+      const targetDir = path.resolve(currentDir, newDir.replace(/^~/, os.homedir()));
+      
+      try {
+        process.chdir(targetDir);
+        currentDir = process.cwd();
+        
+        if (ws && ws.readyState === 1) {
+          ws.send(JSON.stringify({ type: 'cwd', content: getShortDir(currentDir) }));
+        }
+        
+        resolve({ success: true, cwd: getShortDir(currentDir) });
+      } catch (err) {
+        if (ws && ws.readyState === 1) {
+          ws.send(JSON.stringify({ type: 'error', content: `cd: ${err.message}` }));
+        }
+        resolve({ success: false, error: err.message });
+      }
+      return;
+    }
+
+    const proc = spawn(shell, [...shellArgs, command], {
+      cwd: currentDir,
+      env: { ...process.env, FORCE_COLOR: '1' },
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', (data) => {
+      const text = data.toString();
+      stdout += text;
+      if (ws && ws.readyState === 1) {
+        ws.send(JSON.stringify({ type: 'output', content: text }));
+      }
+    });
+
+    proc.stderr.on('data', (data) => {
+      const text = data.toString();
+      stderr += text;
+      if (ws && ws.readyState === 1) {
+        ws.send(JSON.stringify({ type: 'error', content: text }));
+      }
+    });
+
+    proc.on('close', (code) => {
+      resolve({
+        success: code === 0,
+        stdout,
+        stderr,
+        exitCode: code,
+        cwd: getShortDir(currentDir),
+      });
+    });
+
+    proc.on('error', (err) => {
+      if (ws && ws.readyState === 1) {
+        ws.send(JSON.stringify({ type: 'error', content: err.message }));
+      }
+      resolve({ success: false, error: err.message });
+    });
+  });
+}
+
+// Create Express app
+const app = express();
+app.use(cors({
+  origin: '*', // Allow all origins since we're on localhost
+  methods: ['GET', 'POST'],
+}));
+app.use(express.json());
+
+// Health check endpoint
+app.get('/health', (req, res) => {
+  res.json({
+    status: 'ok',
+    version: '1.0.0',
+    platform: process.platform,
+    cwd: getShortDir(currentDir),
+  });
+});
+
+// Check tool status
+app.get('/tools/:tool', async (req, res) => {
+  const { tool } = req.params;
+  const installed = await checkToolInstalled(tool);
+  const version = installed ? await getToolVersion(tool) : null;
+  
+  res.json({
+    tool,
+    installed,
+    version,
+  });
+});
+
+// Install tool
+app.post('/tools/:tool/install', async (req, res) => {
+  const { tool } = req.params;
+  const result = await installTool(tool, null);
+  res.json(result);
+});
+
+// Execute command (REST fallback)
+app.post('/execute', async (req, res) => {
+  const { command } = req.body;
+  
+  if (!command) {
+    return res.status(400).json({ error: 'Command is required' });
+  }
+
+  console.log(`${colors.dim}[CMD]${colors.reset} ${command}`);
+  
+  const result = await executeCommand(command, null);
+  res.json(result);
+});
+
+// Get current directory
+app.get('/cwd', (req, res) => {
+  res.json({ cwd: getShortDir(currentDir) });
+});
+
+// Create HTTP server
+const server = http.createServer(app);
+
+// Create WebSocket server
+const wss = new WebSocketServer({ server, path: '/ws' });
+
+wss.on('connection', (ws) => {
+  console.log(`${colors.green}✓${colors.reset} Client connected via WebSocket`);
+  
+  // Send initial state
+  ws.send(JSON.stringify({ type: 'cwd', content: getShortDir(currentDir) }));
+  
+  ws.on('message', async (message) => {
+    try {
+      const data = JSON.parse(message.toString());
+      
+      if (data.type === 'command') {
+        console.log(`${colors.dim}[CMD]${colors.reset} ${data.content}`);
+        await executeCommand(data.content, ws);
+      } else if (data.type === 'install') {
+        console.log(`${colors.dim}[INSTALL]${colors.reset} ${data.tool}`);
+        await installTool(data.tool, ws);
+      }
+    } catch (err) {
+      console.error(`${colors.red}Error:${colors.reset}`, err.message);
+      ws.send(JSON.stringify({ type: 'error', content: err.message }));
+    }
+  });
+
+  ws.on('close', () => {
+    console.log(`${colors.yellow}○${colors.reset} Client disconnected`);
+  });
+});
+
+// Start server
+server.listen(PORT, HOST, () => {
+  printBanner();
+  
+  console.log(`${colors.green}✓${colors.reset} Agent running on ${colors.cyan}http://${HOST}:${PORT}${colors.reset}`);
+  console.log(`${colors.green}✓${colors.reset} WebSocket available at ${colors.cyan}ws://${HOST}:${PORT}/ws${colors.reset}`);
+  console.log(`${colors.green}✓${colors.reset} Working directory: ${colors.cyan}${getShortDir(currentDir)}${colors.reset}`);
+  console.log('');
+  console.log(`${colors.dim}Press Ctrl+C to stop the agent${colors.reset}`);
+  console.log('');
+});
+
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+  console.log(`\n${colors.yellow}Shutting down agent...${colors.reset}`);
+  server.close(() => {
+    console.log(`${colors.green}✓${colors.reset} Agent stopped`);
+    process.exit(0);
+  });
+});
+
+process.on('SIGTERM', () => {
+  server.close(() => {
+    process.exit(0);
+  });
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "web-terminal-agent",
+  "version": "1.0.0",
+  "description": "Local agent for Web Terminal - enables browser-based terminal access to your computer. Run CLI tools like Claude Code through a friendly web interface.",
+  "main": "index.js",
+  "bin": {
+    "web-terminal-agent": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "terminal",
+    "web",
+    "agent",
+    "cli",
+    "shell",
+    "claude-code",
+    "browser-terminal",
+    "remote-terminal",
+    "web-terminal"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "homepage": "",
+  "bugs": {
+    "url": ""
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "ws": "^8.14.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ]
+}