terminal-expose 1.0.0 → 1.2.0

package/README.md

@@ -1,8 +1,8 @@
 # Terminal Expose
 
-Read-only terminal sharing from your own machine.
+Interactive terminal sharing from your own machine.
 
-`terminal-expose` starts a real shell or command on the host where it is run, prints a private viewer URL, and streams the terminal output to anyone who opens that URL.
+`terminal-expose` starts a real shell or command on the host where it is run, prints a private URL, and allows collaborative, interactive access to anyone who opens that URL.
 
 ## Install
 
@@ -34,15 +34,15 @@ terminal-expose bash -lc "npm test"
 The CLI prints a URL like:
 
 ```text
-Local URL : http://localhost:3000/s/<token>
-LAN URL   : http://192.168.1.10:3000/s/<token>
+Local URL : http://localhost:5555/s/<token>
+LAN URL   : http://192.168.1.10:5555/s/<token>
 ```
 
-Share the full token URL with the viewer. Viewers are read-only.
+Share the full token URL with your collaborators. They will have full read and write access to the terminal.
 
 ## Public Internet Access
 
-For quick public sharing, start a localtunnel:
+For quick public sharing, start a secure edge tunnel (powered by Cloudflare Quick Tunnels):
 
 ```sh
 terminal-expose --public bash
@@ -51,22 +51,17 @@ terminal-expose --public bash
 The CLI prints a URL like:
 
 ```text
-Public URL: https://random-name.loca.lt/s/<token>
-Tunnel password: <localtunnel-password>
+Public URL: https://random-name.trycloudflare.com/s/<token>
 ```
 
-You can request a custom localtunnel subdomain:
+_(Note: Custom subdomains are not currently supported by free Cloudflare Quick Tunnels.)_
 
-```sh
-terminal-expose --public --subdomain my-terminal-demo bash
-```
-
-The tunnel URL works outside your Wi-Fi as long as the CLI is still running. If `loca.lt` asks the viewer for a tunnel password, share the printed tunnel password too.
+The tunnel URL works outside your Wi-Fi as long as the CLI is still running.
 
-For a permanent setup, run it on a public server or forward TCP port `3000` to the machine running the CLI:
+For a permanent setup, run it on a public server or forward TCP port 5555 to the machine running the CLI:
 
 ```sh
-EXTERNAL_URL="http://YOUR_PUBLIC_IP:3000" terminal-expose bash
+EXTERNAL_URL="http://YOUR_PUBLIC_IP:5555" terminal-expose bash
 ```
 
 ## Options
@@ -77,10 +72,9 @@ Use environment variables:
 PORT=4000 terminal-expose bash
 SESSION_TOKEN="change-this-secret" terminal-expose bash
 PUBLIC_TUNNEL=1 terminal-expose bash
-TUNNEL_SUBDOMAIN="my-terminal-demo" PUBLIC_TUNNEL=1 terminal-expose bash
 TERM_COLS=160 TERM_ROWS=48 terminal-expose bash
 ```
 
 ## Security
 
-Anyone with the full URL can watch the session. Do not type passwords, API keys, or private commands in a shared terminal.
+Anyone with the full URL can view and interact with the session. Do not type passwords, API keys, or private commands in a shared terminal.

package/index.js

@@ -1,81 +1,21 @@
 #!/usr/bin/env node
 
-const express = require("express");
 const http = require("http");
-const { Server } = require("socket.io");
-const crypto = require("crypto");
-const https = require("https");
-const os = require("os");
-const pty = require("node-pty");
-const path = require("path");
-const localtunnel = require("localtunnel");
+const { parseArgs } = require("./src/utils/args");
+const { getDefaultShell, getLanUrls } = require("./src/utils/system");
+const { TerminalSession } = require("./src/core/terminal");
+const { setupSocket } = require("./src/core/socket");
+const { startPublicTunnel } = require("./src/core/tunnel");
+const { createApp } = require("./src/server/app");
 
-const app = express();
-const server = http.createServer(app);
+const { PORT, HOST, SESSION_TOKEN, EXTERNAL_URL } = require("./src/config/env");
 
-const PORT = Number(process.env.PORT || 3000);
-const HOST = process.env.HOST || "0.0.0.0";
-const MAX_BUFFER = Number(process.env.MAX_BUFFER || 100000);
-const ECHO_TO_STDOUT = process.env.ECHO_TO_STDOUT !== "0";
-const SESSION_TOKEN =
-  process.env.SESSION_TOKEN || crypto.randomBytes(18).toString("base64url");
+// arguments
 const rawArgs = process.argv.slice(2);
 
-function parseArgs(args) {
-  const options = {
-    publicTunnel: false,
-    tunnelSubdomain: process.env.TUNNEL_SUBDOMAIN || null,
-    tunnelHost: process.env.TUNNEL_HOST || undefined,
-  };
-  const commandArgs = [];
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-
-    if (arg === "--public" || arg === "--tunnel") {
-      options.publicTunnel = true;
-      continue;
-    }
-
-    if (arg === "--subdomain") {
-      options.tunnelSubdomain = args[index + 1] || null;
-      index += 1;
-      continue;
-    }
-
-    if (arg.startsWith("--subdomain=")) {
-      options.tunnelSubdomain = arg.slice("--subdomain=".length) || null;
-      continue;
-    }
-
-    if (arg === "--tunnel-host") {
-      options.tunnelHost = args[index + 1] || undefined;
-      index += 1;
-      continue;
-    }
-
-    if (arg.startsWith("--tunnel-host=")) {
-      options.tunnelHost = arg.slice("--tunnel-host=".length) || undefined;
-      continue;
-    }
-
-    commandArgs.push(arg);
-  }
-
-  if (
-    process.env.PUBLIC_TUNNEL === "1" ||
-    process.env.PUBLIC_TUNNEL === "true"
-  ) {
-    options.publicTunnel = true;
-  }
-
-  return { options, commandArgs };
-}
-
-const { options, commandArgs: command } = parseArgs(rawArgs);
-
 if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
   console.log(`Terminal Expose
+Interactive terminal session sharing over HTTP and WebSocket.
 
 Usage:
   terminal-expose [options] [command] [args...]
@@ -86,23 +26,18 @@ Examples:
   terminal-expose zsh
   terminal-expose bash -lc "cd ~/project && npm test"
   terminal-expose --public bash
-  terminal-expose --public --subdomain my-demo bash
 
 Environment:
-  PORT=3000
+  PORT=5555
   HOST=0.0.0.0
   SESSION_TOKEN=<custom-token>
-  EXTERNAL_URL=http://YOUR_PUBLIC_IP:3000
+  EXTERNAL_URL=http://YOUR_PUBLIC_IP:5555
   PUBLIC_TUNNEL=1
-  TUNNEL_SUBDOMAIN=my-demo
-  TUNNEL_HOST=https://localtunnel.me
   TERM_COLS=120
   TERM_ROWS=40
 
 Options:
   --public, --tunnel          Create a public HTTPS tunnel.
-  --subdomain <name>          Request a localtunnel subdomain.
-  --tunnel-host <url>         Use a different localtunnel server.
 `);
   process.exit(0);
 }
@@ -113,385 +48,41 @@ if (rawArgs.includes("--version") || rawArgs.includes("-v")) {
   process.exit(0);
 }
 
-const shellCommand =
-  command.length > 0
-    ? command[0]
-    : process.platform === "win32"
-      ? "powershell.exe"
-      : process.env.SHELL || "bash";
-const shellArgs = command.length > 0 ? command.slice(1) : [];
-
-function getLanUrls() {
-  const urls = [];
-  const interfaces = os.networkInterfaces();
-
-  Object.values(interfaces).forEach((addresses = []) => {
-    addresses
-      .filter((address) => address.family === "IPv4" && !address.internal)
-      .forEach((address) => {
-        urls.push(`http://${address.address}:${PORT}/s/${SESSION_TOKEN}`);
-      });
-  });
-
-  return urls;
-}
-
-function getLocaltunnelPassword() {
-  return new Promise((resolve) => {
-    let settled = false;
-
-    function finish(value) {
-      if (settled) {
-        return;
-      }
-
-      settled = true;
-      resolve(value);
-    }
-
-    const request = https.get("https://loca.lt/mytunnelpassword", (response) => {
-      if (response.statusCode !== 200) {
-        response.resume();
-        finish(null);
-        return;
-      }
-
-      let body = "";
-      response.setEncoding("utf8");
-      response.on("data", (chunk) => {
-        body += chunk;
-      });
-      response.on("end", () => {
-        finish(body.trim() || null);
-      });
-    });
-
-    request.setTimeout(3000, () => {
-      request.destroy();
-      finish(null);
-    });
-
-    request.on("error", () => {
-      finish(null);
-    });
-  });
-}
-
-async function startPublicTunnel() {
-  const localHost =
-    HOST === "0.0.0.0" || HOST === "::" ? "127.0.0.1" : HOST;
-  const tunnelOptions = {
-    port: PORT,
-    local_host: localHost,
-  };
-
-  if (options.tunnelSubdomain) {
-    tunnelOptions.subdomain = options.tunnelSubdomain;
-  }
-
-  if (options.tunnelHost) {
-    tunnelOptions.host = options.tunnelHost;
-  }
-
-  console.log("Public tunnel: starting...");
-
-  const tunnel = await localtunnel(tunnelOptions);
-  const publicUrl = `${tunnel.url.replace(/\/$/, "")}/s/${SESSION_TOKEN}`;
-
-  console.log(`Public URL: ${publicUrl}`);
-
-  if (new URL(tunnel.url).hostname.endsWith(".loca.lt")) {
-    const password = await getLocaltunnelPassword();
-
-    if (password) {
-      console.log(`Tunnel password: ${password}`);
-    }
-  }
-
-  tunnel.on("error", (error) => {
-    console.error(`Public tunnel error: ${error.message}`);
-  });
-
-  tunnel.on("close", () => {
-    console.log("Public tunnel closed.");
-  });
-
-  ["SIGINT", "SIGTERM"].forEach((signal) => {
-    process.once(signal, () => {
-      tunnel.close();
-      process.kill(process.pid, signal);
-    });
-  });
-
-  return tunnel;
-}
-
-const VIEWER_HTML = String.raw`<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Terminal Viewer</title>
-    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/xterm/css/xterm.css" />
-    <style>
-      html,
-      body {
-        margin: 0;
-        padding: 0;
-        background: #050505;
-        color: #f2f2f2;
-        width: 100%;
-        height: 100%;
-        overflow: hidden;
-        font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-      }
-
-      .topbar {
-        align-items: center;
-        background: #111;
-        border-bottom: 1px solid #2a2a2a;
-        box-sizing: border-box;
-        display: flex;
-        gap: 12px;
-        height: 42px;
-        justify-content: space-between;
-        padding: 0 14px;
-      }
-
-      .title {
-        font-size: 13px;
-        font-weight: 650;
-      }
-
-      .status {
-        align-items: center;
-        color: #b8b8b8;
-        display: flex;
-        font-size: 12px;
-        gap: 8px;
-        min-width: 0;
-      }
-
-      .dot {
-        background: #9ca3af;
-        border-radius: 999px;
-        flex: 0 0 auto;
-        height: 8px;
-        width: 8px;
-      }
-
-      .dot.connected {
-        background: #22c55e;
-      }
-
-      .dot.disconnected {
-        background: #ef4444;
-      }
-
-      #terminal {
-        width: 100vw;
-        height: calc(100vh - 42px);
-      }
-
-      .xterm {
-        height: 100%;
-      }
-    </style>
-  </head>
-  <body>
-    <header class="topbar">
-      <div class="title">Terminal Expose</div>
-      <div class="status">
-        <span id="dot" class="dot"></span>
-        <span id="status">Connecting</span>
-      </div>
-    </header>
-    <div id="terminal"></div>
-    <script src="/socket.io/socket.io.js"></script>
-    <script src="https://cdn.jsdelivr.net/npm/xterm/lib/xterm.js"></script>
-    <script>
-      const token = window.location.pathname.split('/').filter(Boolean).pop();
-      const statusText = document.getElementById('status');
-      const dot = document.getElementById('dot');
-      const term = new Terminal({
-        disableStdin: true,
-        cursorBlink: false,
-        convertEol: true,
-        fontFamily: '"JetBrains Mono", "SFMono-Regular", Consolas, monospace',
-        fontSize: 14,
-        scrollback: 10000,
-        theme: {
-          background: '#050505',
-          foreground: '#f4f4f5',
-          cursor: '#f4f4f5',
-          black: '#18181b',
-          red: '#ef4444',
-          green: '#22c55e',
-          yellow: '#eab308',
-          blue: '#3b82f6',
-          magenta: '#a855f7',
-          cyan: '#06b6d4',
-          white: '#e4e4e7'
-        }
-      });
-
-      term.open(document.getElementById('terminal'));
-
-      function setStatus(text, className) {
-        statusText.textContent = text;
-        dot.className = 'dot ' + (className || '');
-      }
-
-      const socket = io({
-        auth: { token },
-        reconnectionAttempts: 10,
-        timeout: 5000
-      });
-
-      socket.on('connect', () => {
-        setStatus('Connected', 'connected');
-      });
-
-      socket.on('terminal-output', (data) => {
-        term.write(data);
-      });
-
-      socket.on('terminal-exit', ({ exitCode, signal }) => {
-        const suffix = signal ? 'signal ' + signal : 'exit code ' + exitCode;
-        setStatus('Command ended: ' + suffix, 'disconnected');
-        term.writeln('\r\n[Command ended: ' + suffix + ']');
-      });
-
-      socket.on('connect_error', (error) => {
-        setStatus(error.message || 'Connection error', 'disconnected');
-      });
-
-      socket.on('disconnect', () => {
-        setStatus('Disconnected', 'disconnected');
-      });
-    </script>
-  </body>
-</html>`;
-
-const io = new Server(server, {
-  cors: {
-    origin: false,
-  },
-});
-
-io.use((socket, next) => {
-  const token = socket.handshake.auth?.token;
-
-  if (token !== SESSION_TOKEN) {
-    return next(new Error("unauthorized"));
-  }
-
-  return next();
-});
-
-const shell = pty.spawn(shellCommand, shellArgs, {
-  name: "xterm-256color",
-  cols: Number(process.env.TERM_COLS || 120),
-  rows: Number(process.env.TERM_ROWS || 40),
-  cwd: process.env.WORKDIR || process.cwd(),
-  env: {
-    ...process.env,
-    TERM: "xterm-256color",
-  },
-});
-
-let terminalBuffer = "";
-let terminalExit = null;
-
-if (process.stdin.isTTY) {
-  process.stdin.setRawMode(true);
-}
-
-process.stdin.resume();
-process.stdin.on("data", (data) => {
-  shell.write(data);
-});
-
-shell.onData((data) => {
-  if (ECHO_TO_STDOUT) {
-    process.stdout.write(data);
-  }
-
-  terminalBuffer += data;
-
-  if (terminalBuffer.length > MAX_BUFFER) {
-    terminalBuffer = terminalBuffer.slice(-MAX_BUFFER);
-  }
-
-  io.emit("terminal-output", data);
-});
-
-shell.onExit(({ exitCode, signal }) => {
-  terminalExit = { exitCode, signal };
-  io.emit("terminal-exit", terminalExit);
-  console.log(`Terminal command exited: code=${exitCode} signal=${signal}`);
+const { options, commandArgs: command } = parseArgs(rawArgs);
 
-  if (process.stdin.isTTY) {
-    process.stdin.setRawMode(false);
-  }
+const shellCommand = command.length > 0 ? command[0] : getDefaultShell();
+const shellArgs = command.length > 0 ? command.slice(1) : [];
 
-  setTimeout(() => {
-    process.exit(exitCode ?? 0);
-  }, 250);
-});
+// Initialize Terminal
+const terminalSession = new TerminalSession(shellCommand, shellArgs);
 
-app.use("/assets", express.static(path.join(__dirname, "public")));
+// Initialize Express App
+let ioInstance = null;
+const app = createApp(() => ioInstance, terminalSession);
+const server = http.createServer(app);
 
-app.get("/", (_, res) => {
-  res.type("html").send(`<!doctype html>
-    <html>
-      <head>
-        <meta charset="utf-8" />
-        <title>Terminal Expose</title>
-      </head>
-      <body style="font-family: system-ui, sans-serif; line-height: 1.5; padding: 32px;">
-        <h1>Terminal Expose</h1>
-        <p>This server is running. Use the private session URL printed in the container logs.</p>
-      </body>
-    </html>`);
-});
+// Initialize Socket.io
+ioInstance = setupSocket(server, terminalSession);
 
-app.get("/health", (_, res) => {
-  res.json({
-    ok: true,
-    viewers: io.engine.clientsCount,
-    exited: terminalExit,
+// Close server and process gracefully on terminal exit
+terminalSession.on("exit", () => {
+  console.log("Shutting down server port...");
+  server.close(() => {
+    // Ensure process is fully killed after server cleanly exits
+    process.exit(terminalSession.exit?.exitCode ?? 0);
   });
-});
-
-app.get("/s/:token", (req, res) => {
-  if (req.params.token !== SESSION_TOKEN) {
-    return res.status(403).send("Invalid session token");
-  }
-
-  res.type("html").send(VIEWER_HTML);
-});
 
-io.on("connection", (socket) => {
-  console.log(`Viewer connected: ${socket.id}`);
-
-  if (terminalBuffer) {
-    socket.emit("terminal-output", terminalBuffer);
-  }
-
-  if (terminalExit) {
-    socket.emit("terminal-exit", terminalExit);
-  }
-
-  socket.on("disconnect", () => {
-    console.log(`Viewer disconnected: ${socket.id}`);
-  });
+  // Force exit if server.close() hangs (e.g., active keep-alive connections)
+  setTimeout(
+    () => process.exit(terminalSession.exit?.exitCode ?? 0),
+    1000,
+  ).unref();
 });
 
 server.listen(PORT, HOST, () => {
   const localUrl = `http://localhost:${PORT}/s/${SESSION_TOKEN}`;
-  const externalUrl = process.env.EXTERNAL_URL
-    ? `${process.env.EXTERNAL_URL.replace(/\/$/, "")}/s/${SESSION_TOKEN}`
+  const externalUrl = EXTERNAL_URL
+    ? `${EXTERNAL_URL.replace(/\/$/, "")}/s/${SESSION_TOKEN}`
     : null;
 
   console.log("\n==============================");
@@ -500,20 +91,22 @@ server.listen(PORT, HOST, () => {
   console.log(`Command   : ${[shellCommand, ...shellArgs].join(" ")}`);
   console.log(`Local URL : ${localUrl}`);
 
-  getLanUrls().forEach((url) => console.log(`LAN URL   : ${url}`));
+  getLanUrls({ port: PORT, session_token: SESSION_TOKEN }).forEach((url) =>
+    console.log(`LAN URL   : ${url}`),
+  );
 
   if (externalUrl) {
     console.log(`Public URL: ${externalUrl}`);
   }
 
   if (options.publicTunnel) {
-    startPublicTunnel().catch((error) => {
+    startPublicTunnel(options, { HOST, PORT, SESSION_TOKEN }).catch((error) => {
       console.error(`Public tunnel failed: ${error.message}`);
     });
   }
 
   console.log("");
-  console.log("Share only the session URL with trusted viewers.");
+  console.log("Share only the session URL with trusted collaborators.");
   console.log("Use --public for internet access without router forwarding.");
   console.log("==============================\n");
 });

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "terminal-expose",
-  "version": "1.0.0",
-  "description": "Read-only terminal session sharing over HTTP and WebSocket.",
+  "version": "1.2.0",
+  "description": "Interactive terminal session sharing over HTTP and WebSocket.",
   "main": "index.js",
   "bin": {
     "terminal-expose": "index.js"
   },
   "files": [
     "index.js",
+    "src",
     "public"
   ],
   "scripts": {
@@ -32,13 +33,8 @@
   },
   "dependencies": {
     "express": "^5.2.1",
-    "localtunnel": "^2.0.2",
     "node-pty": "^1.1.0",
-    "socket.io": "^4.8.3"
-  },
-  "overrides": {
-    "localtunnel": {
-      "axios": "^1.16.1"
-    }
+    "socket.io": "^4.8.3",
+    "untun": "^0.1.3"
   }
 }

package/src/config/env.js

@@ -0,0 +1,24 @@
+const crypto = require("crypto");
+
+const PORT = Number(process.env.PORT || 5555);
+const HOST = process.env.HOST || "0.0.0.0";
+const MAX_BUFFER = Number(process.env.MAX_BUFFER || 100000);
+const ECHO_TO_STDOUT = process.env.ECHO_TO_STDOUT !== "0";
+const SESSION_TOKEN =
+  process.env.SESSION_TOKEN || crypto.randomBytes(18).toString("base64url");
+const TERM_COLS = Number(process.env.TERM_COLS || 120);
+const TERM_ROWS = Number(process.env.TERM_ROWS || 40);
+const WORKDIR = process.env.WORKDIR || process.cwd();
+const EXTERNAL_URL = process.env.EXTERNAL_URL || null;
+
+module.exports = {
+  PORT,
+  HOST,
+  MAX_BUFFER,
+  ECHO_TO_STDOUT,
+  SESSION_TOKEN,
+  TERM_COLS,
+  TERM_ROWS,
+  WORKDIR,
+  EXTERNAL_URL,
+};