termbeam 0.0.7 → 0.0.9

package/README.md

@@ -1,40 +1,21 @@
-<div align="center">
+# TermBeam
 
-# 📡 TermBeam
-
-**Beam your terminal to any device**
+**Beam your terminal to any device.**
 
 [![npm version](https://img.shields.io/npm/v/termbeam.svg)](https://www.npmjs.com/package/termbeam)
 [![CI](https://github.com/dorlugasigal/TermBeam/actions/workflows/ci.yml/badge.svg)](https://github.com/dorlugasigal/TermBeam/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/dorlugasigal/TermBeam/coverage-data/endpoint.json)](https://github.com/dorlugasigal/TermBeam/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
-
-Access your terminal from your phone, tablet, or any browser.
-Multi-session, mobile-optimized, with touch controls.
 
-[Getting Started](#-quick-start) · [Demo](#-demo) · [Documentation](https://dorlugasigal.github.io/TermBeam/) · [Contributing](CONTRIBUTING.md)
+TermBeam lets you access your terminal from a phone, tablet, or any browser — no SSH, no port forwarding, no config files. Run one command and scan the QR code.
 
-</div>
+I built this because I kept needing to run quick commands on my dev machine while away from my desk, and SSH on a phone is painful. TermBeam gives you a real terminal with a touch-friendly UI that actually works on small screens.
 
----
+[Full documentation](https://dorlugasigal.github.io/TermBeam/)
 
 https://github.com/user-attachments/assets/c91ca15d-0c84-400f-bbfa-3d58d1be07ee
 
-## ✨ Features
-
-- 📱 **Mobile-first UI** — Touch-friendly interface designed for phones and tablets
-- 🖥️ **Multi-session** — Run multiple terminal sessions simultaneously
-- 🔐 **Password auth** — Token-based authentication with rate limiting
-- 📂 **Folder browser** — Visual directory picker with breadcrumb navigation
-- 👆 **Touch controls** — Arrow keys, Ctrl shortcuts, Tab, Esc via on-screen touch bar
-- 🔤 **Nerd Font support** — Full glyph rendering with JetBrains Mono Nerd Font
-- 📲 **QR code** — Scan to connect instantly from your phone
-- 🌐 **DevTunnel** — Optional public URL for remote access from anywhere
-- 🔍 **Adjustable font size** — Pinch or button zoom for any screen
-- ↔️ **Swipe to delete** — iOS-style session management
-- 🔄 **Smart versioning** — Shows git hash in dev, clean version from npm
-
-## 🚀 Quick Start
+## Quick Start
 
 ```bash
 npx termbeam
@@ -47,124 +28,81 @@ npm install -g termbeam
 termbeam
 ```
 
-That's it. Scan the QR code printed in your terminal, or open the URL on any device.
+Scan the QR code printed in your terminal, or open the URL on any device.
 
-### With password protection (recommended)
+### Password protection (recommended)
 
 ```bash
-# Auto-generate a secure password
 termbeam --generate-password
 
-# Or set your own
+# or set your own
 termbeam --password mysecret
 ```
 
-### Remote access from anywhere
-
-```bash
-termbeam --tunnel --generate-password
-```
+## Features
 
-> Requires the [Azure Dev Tunnels CLI](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started):
->
-> - **Windows:** `winget install Microsoft.devtunnel`
-> - **macOS:** `brew install --cask devtunnel`
-> - **Linux:** `curl -sL https://aka.ms/DevTunnelCliInstall | bash`
+- **Mobile-first UI** with on-screen touch bar (arrow keys, Tab, Ctrl shortcuts, Esc) and swipe-to-delete session management
+- **Multiple sessions** running simultaneously, managed from a single hub page — shows connected client count per session
+- **Password auth** with token-based cookies and rate-limited login
+- **Folder browser** to pick working directories without typing paths
+- **Initial command** — optionally launch a session straight into `htop`, `vim`, or any command
+- **Shell detection** — auto-detects your shell on all platforms (PowerShell, cmd, bash, zsh, Git Bash, WSL)
+- **QR code on startup** for instant phone connection
+- **Light/dark theme** with persistent preference
+- **Adjustable font size** via status bar controls, saved across sessions
+- **Remote access via [DevTunnel](#remote-access)** — ephemeral or persisted public URLs
 
-## 📖 Usage
+## Remote Access
 
 ```bash
-# Start with your default shell
-termbeam
-
-# Use a specific shell
-termbeam /bin/bash
-
-# Custom port and listen on all interfaces (LAN access)
-termbeam --port 8080 --host 0.0.0.0
-
-# Public tunnel + password (access from anywhere)
+# One-off tunnel (deleted on shutdown)
 termbeam --tunnel --generate-password
-```
-
-### CLI Options
-
-| Flag                  | Description                     | Default     |
-| --------------------- | ------------------------------- | ----------- |
-| `--password <pw>`     | Set access password             | None        |
-| `--generate-password` | Auto-generate a secure password | —           |
-| `--tunnel`            | Create a public devtunnel URL   | Off         |
-| `--port <port>`       | Server port                     | `3456`      |
-| `--host <addr>`       | Bind address                    | `127.0.0.1` |
-| `-h, --help`          | Show help                       | —           |
-| `-v, --version`       | Show version                    | —           |
 
-### Environment Variables
-
-| Variable            | Description                     |
-| ------------------- | ------------------------------- |
-| `PORT`              | Server port (overrides default) |
-| `TERMBEAM_PASSWORD` | Access password                 |
-| `TERMBEAM_CWD`      | Default working directory       |
-
-## 🔒 Security
+# Persisted tunnel (stable URL you can bookmark, reused across restarts, 30-day expiry)
+termbeam --persisted-tunnel --generate-password
+```
 
-TermBeam is designed for **local network use**. Key security features:
+Requires the [Dev Tunnels CLI](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started):
 
-- 🔑 **Token-based auth** with secure, httpOnly cookies (24-hour expiry)
-- 🛡️ **Rate limiting** on login (5 attempts per minute)
-- 🔒 **Security headers** (X-Frame-Options, X-Content-Type-Options, CSP, etc.)
-- 🏠 **Localhost by default** — requires explicit `--host 0.0.0.0` for LAN access
+- **Windows:** `winget install Microsoft.devtunnel`
+- **macOS:** `brew install --cask devtunnel`
+- **Linux:** `curl -sL https://aka.ms/DevTunnelCliInstall | bash`
 
-> ⚠️ **Always use a password when exposing to any network.** See the [Security Guide](https://dorlugasigal.github.io/TermBeam/security/) for production deployment tips.
+Persisted tunnels save a tunnel ID to `~/.termbeam/tunnel.json` so the URL stays the same between sessions.
 
-## 🏗️ Architecture
+## CLI Reference
 
-```
-termbeam/
-├── bin/termbeam.js            # CLI entry point
-├── src/
-│   ├── server.js              # Main orchestrator
-│   ├── cli.js                 # Argument parsing & help
-│   ├── auth.js                # Authentication & rate limiting
-│   ├── sessions.js            # PTY session lifecycle
-│   ├── routes.js              # Express HTTP routes
-│   ├── websocket.js           # WebSocket terminal I/O
-│   ├── tunnel.js              # DevTunnel integration
-│   └── version.js             # Smart version detection
-├── public/
-│   ├── index.html             # Session manager UI (mobile)
-│   └── terminal.html          # Terminal UI (xterm.js)
-├── test/                      # Unit tests (node:test)
-├── docs/                      # MkDocs documentation
-└── .github/workflows/         # CI, Release, Docs deployment
+```bash
+termbeam [shell] [args...]        # start with a specific shell (default: auto-detect)
+termbeam --port 8080              # custom port (default: 3456)
+termbeam --host 127.0.0.1        # restrict to localhost (default: 0.0.0.0)
 ```
 
-See the [Architecture Guide](https://dorlugasigal.github.io/TermBeam/architecture/) for details.
+| Flag                  | Description                              | Default     |
+| --------------------- | ---------------------------------------- | ----------- |
+| `--password <pw>`     | Set access password                      | None        |
+| `--generate-password` | Auto-generate a secure password          | —           |
+| `--tunnel`            | Create an ephemeral devtunnel URL        | Off         |
+| `--persisted-tunnel`  | Create a reusable devtunnel URL          | Off         |
+| `--port <port>`       | Server port                              | `3456`      |
+| `--host <addr>`       | Bind address                             | `0.0.0.0`   |
 
-## 📚 Documentation
+Environment variables: `PORT`, `TERMBEAM_PASSWORD`, `TERMBEAM_CWD` (see [Configuration docs](https://dorlugasigal.github.io/TermBeam/configuration/)).
 
-Full documentation is available at **[dorlugasigal.github.io/TermBeam](https://dorlugasigal.github.io/TermBeam/)**
+## Security
 
-- [Getting Started](https://dorlugasigal.github.io/TermBeam/getting-started/)
-- [Configuration](https://dorlugasigal.github.io/TermBeam/configuration/)
-- [Security](https://dorlugasigal.github.io/TermBeam/security/)
-- [API Reference](https://dorlugasigal.github.io/TermBeam/api/)
-- [Architecture](https://dorlugasigal.github.io/TermBeam/architecture/)
+TermBeam binds to all interfaces (`0.0.0.0`) by default, so it's accessible on your local network out of the box. **Always set a password** when running on a shared network, or pass `--host 127.0.0.1` to restrict access to your machine only.
 
-## 🤝 Contributing
+Auth uses secure httpOnly cookies with 24-hour expiry, login is rate-limited to 5 attempts per minute, and security headers (X-Frame-Options, X-Content-Type-Options, etc.) are set on all responses. API clients that can't use cookies can authenticate with an `Authorization: Bearer <password>` header. See the [Security Guide](https://dorlugasigal.github.io/TermBeam/security/) for more.
 
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+## Contributing
 
-- Development setup and local workflow
-- Testing guide (Node.js built-in test runner)
-- Commit conventions and PR process
-- Release process (maintainers)
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## 📄 License
+## License
 
-[MIT](LICENSE) — made with ❤️ by [@dorlugasigal](https://github.com/dorlugasigal)
+[MIT](LICENSE)
 
-## 🙏 Acknowledgments
+## Acknowledgments
 
 Special thanks to [@tamirdresher](https://github.com/tamirdresher) for the [blog post](https://www.tamirdresher.com/blog/2026/02/26/squad-remote-control) that inspired the solution idea for this project, and for his [cli-tunnel](https://github.com/tamirdresher/cli-tunnel) implementation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termbeam",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Beam your terminal to any device — mobile-optimized web terminal with multi-session support",
   "main": "src/server.js",
   "bin": {
@@ -10,6 +10,7 @@
     "start": "node bin/termbeam.js",
     "dev": "node bin/termbeam.js --generate-password",
     "test": "node --test test/*.test.js",
+    "test:coverage": "c8 --reporter=text --reporter=lcov --reporter=json-summary --reporter=json node --test --test-reporter=spec --test-reporter-destination=stdout test/*.test.js",
     "prepare": "husky",
     "format": "prettier --write .",
     "lint": "node --check src/*.js bin/*.js",
@@ -62,6 +63,7 @@
     "ws": "^8.19.0"
   },
   "devDependencies": {
+    "c8": "^11.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
     "prettier": "^3.8.1"

package/src/cli.js

@@ -33,28 +33,84 @@ Environment:
 `);
 }
 
+/**
+ * Get ancestor process names on Windows by walking up the process tree.
+ * Fetches all processes in a single wmic call, then walks the tree in memory.
+ */
+function getWindowsAncestors(startPid, maxDepth = 4) {
+  const { execFileSync } = require('child_process');
+  const names = [];
+  const safePid = parseInt(startPid, 10);
+  if (!Number.isFinite(safePid) || safePid <= 0) return names;
+
+  try {
+    const result = execFileSync(
+      'wmic',
+      ['process', 'get', 'Name,ParentProcessId,ProcessId', '/format:csv'],
+      { stdio: ['pipe', 'pipe', 'ignore'], encoding: 'utf8', timeout: 5000 },
+    );
+
+    // Parse CSV output — first non-empty line is the header
+    const lines = result.split(/\r?\n/).filter((l) => l.trim());
+    if (lines.length === 0) return names;
+
+    const header = lines[0].split(',').map((h) => h.trim());
+    const nameIdx = header.indexOf('Name');
+    const pidIdx = header.indexOf('ProcessId');
+    const ppidIdx = header.indexOf('ParentProcessId');
+    if (nameIdx === -1 || pidIdx === -1 || ppidIdx === -1) return names;
+
+    const processes = new Map();
+    for (let i = 1; i < lines.length; i++) {
+      const cols = lines[i].split(',');
+      if (cols.length <= Math.max(nameIdx, pidIdx, ppidIdx)) continue;
+      const pid = parseInt(cols[pidIdx], 10);
+      if (Number.isFinite(pid)) {
+        processes.set(pid, { name: cols[nameIdx].trim().toLowerCase(), ppid: parseInt(cols[ppidIdx], 10) });
+      }
+    }
+
+    // Walk up the tree in memory — no more subprocess calls
+    let currentPid = safePid;
+    for (let i = 0; i < maxDepth; i++) {
+      const proc = processes.get(currentPid);
+      if (!proc) break;
+      console.log(`[termbeam] Process tree: ${proc.name}`);
+      names.push(proc.name);
+      if (!Number.isFinite(proc.ppid) || proc.ppid === 0 || proc.ppid === currentPid) break;
+      currentPid = proc.ppid;
+    }
+  } catch (err) {
+    console.log(`[termbeam] Could not query process tree: ${err.message}`);
+  }
+
+  return names;
+}
+
 function getDefaultShell() {
   const { execFileSync } = require('child_process');
   const ppid = process.ppid;
   console.log(`[termbeam] Detecting shell (parent PID: ${ppid}, platform: ${os.platform()})`);
 
   if (os.platform() === 'win32') {
-    // Detect parent process on Windows via WMIC
-    try {
-      const result = execFileSync(
-        'wmic',
-        ['process', 'where', `ProcessId=${ppid}`, 'get', 'Name', '/value'],
-        { stdio: ['pipe', 'pipe', 'ignore'], encoding: 'utf8', timeout: 3000 },
-      );
-      const match = result.match(/Name=(.+)/);
-      if (match) {
-        const name = match[1].trim().toLowerCase();
-        console.log(`[termbeam] Detected parent process: ${name}`);
-        if (name === 'pwsh.exe') return 'pwsh.exe';
-        if (name === 'powershell.exe') return 'powershell.exe';
+    // Walk up the process tree (up to 4 ancestors) to find the real user shell.
+    // npx/npm on Windows spawns cmd.exe as intermediary, so the immediate
+    // parent is often cmd.exe or node.exe rather than the user's actual shell.
+    const ancestors = getWindowsAncestors(ppid);
+    const preferredShells = ['pwsh.exe', 'powershell.exe'];
+
+    let foundCmd = false;
+    for (const name of ancestors) {
+      if (preferredShells.includes(name)) {
+        console.log(`[termbeam] Found shell in process tree: ${name}`);
+        return name;
       }
-    } catch (err) {
-      console.log(`[termbeam] Could not detect parent process: ${err.message}`);
+      if (name === 'cmd.exe') foundCmd = true;
+    }
+
+    if (foundCmd) {
+      console.log(`[termbeam] Using detected shell: cmd.exe`);
+      return 'cmd.exe';
     }
     const fallback = process.env.COMSPEC || 'cmd.exe';
     console.log(`[termbeam] Falling back to: ${fallback}`);