feat: add file upload to session working directory (#113)

## Summary

Upload files from your phone (or any browser) directly into a terminal
session's working directory.

### Features

- **Upload endpoint**: `POST /api/sessions/:id/upload` — buffers raw
file body and writes to the session's cwd with optional `X-Target-Dir`
override
- **Command Palette action**: "Upload files" under Session category
(Ctrl+K)
- **Confirmation modal**: shows file list with sizes, destination
directory with folder browser
- **Client-side validation**: files exceeding 10 MB shown in red with
Upload button disabled
- **Filename sanitization**: strips path traversal sequences, control
characters, collapses whitespace; atomic dedup via exclusive-create
(`wx` flag) with retry on collision
- **Path security**: rejects relative `X-Target-Dir`, validates absolute
paths, containment check ensures writes stay inside target directory
- **Toast notification**: "3 files uploaded to /path/to/dir" on
completion

### Testing

- 14 new tests covering happy path, dedup, path traversal, invalid
filenames, empty body, oversized files, custom target dir, non-existent
dir, relative dir, non-directory target, read-only dir (skipped on
Windows)
- All tests pass

### Docs

- Updated `docs/api.md`, `docs/usage-guide.md`, `docs/index.md`,
`README.md`, `landing/index.html`

Closes #110

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dorlugasigal

.github/copilot-instructions.md

@@ -5,9 +5,11 @@
 ```bash
 npm test                              # run all tests
 node --test test/auth.test.js         # run a single test file
-npm run test:coverage                 # tests + coverage (c8, 80% threshold)
+npm run test:coverage                 # tests + coverage (c8, 92% threshold)
 npm run lint                          # syntax-check with node --check
 npm run format                        # format with Prettier
+npm run dev                           # start with auto-generated password
+npm start                             # start with defaults
 ```
 
 Pre-commit hooks (Husky + lint-staged) auto-format and syntax-check staged files.
@@ -32,6 +34,14 @@ Pre-commit hooks (Husky + lint-staged) auto-format and syntax-check staged files
 
 **Port isolation:** Integration tests use port `0` (OS-assigned random port) to avoid conflicts. Never hardcode ports in tests.
 
+### Playwright E2E
+
+```bash
+npx playwright test                   # run e2e tests (chromium, sequential)
+```
+
+E2E tests live in `test/e2e-*.test.js` and are excluded from `npm test`. See `playwright.config.js` for retries, reporters, and timeouts.
+
 ## Architecture
 
 TermBeam is a Node.js CLI tool that exposes a local PTY (pseudo-terminal) over HTTP + WebSocket, with a mobile-optimized browser UI.
@@ -44,9 +54,14 @@ TermBeam is a Node.js CLI tool that exposes a local PTY (pseudo-terminal) over H
 - `routes.js` — Express routes for API (`/api/sessions`, `/api/auth`) and pages (`/terminal`, `/login`)
 - `websocket.js` — handles WebSocket messages (`attach`, `input`, `resize`, `output`, `exit`)
 - `tunnel.js` — optional DevTunnel integration for public URLs
+- `devtunnel-install.js` — DevTunnel CLI installer (cross-platform helper)
+- `preview.js` — local preview proxy for forwarding requests to a port
 - `logger.js` — structured logger with levels (error/warn/info/debug)
 - `shells.js` — cross-platform shell detection
 - `version.js` — detects version from package.json
+- `git.js` — git metadata and status parsing
+- `interactive.js` — interactive CLI setup wizard
+- `prompts.js` — reusable CLI prompt utilities
 
 **CLI subcommands** dispatched in `bin/termbeam.js` before loading the server:
 
@@ -75,9 +90,17 @@ TermBeam is a Node.js CLI tool that exposes a local PTY (pseudo-terminal) over H
 - **Prettier formatting** — single quotes, trailing commas, 100 char width, semicolons (`.prettierrc`)
 - **Cross-platform support** — must work on Windows, macOS, and Linux; CI tests on Ubuntu + Windows with Node 18, 20, 22
 - **PTY session cleanup** — `pty.kill()` is async; the `onExit` callback removes the session from the Map
-- **Coverage exclusion** — `src/tunnel.js` is excluded from coverage (requires external DevTunnel CLI)
+- **Coverage exclusion** — `src/tunnel.js` and `src/devtunnel-install.js` are excluded from coverage (requires external DevTunnel CLI)
 - **Connection config** — server writes `~/.termbeam/connection.json` on start (port, host, password) for `termbeam resume` auto-discovery; removed on shutdown
 
+## Environment Variables
+
+- `PORT` — server port (default: 3456)
+- `TERMBEAM_PASSWORD` / `PTY_PASSWORD` — access password
+- `TERMBEAM_CWD` / `PTY_CWD` — working directory
+- `TERMBEAM_LOG_LEVEL` — log level (default: info)
+- `TERMBEAM_CONFIG_DIR` — location for `connection.json` (default: `~/.termbeam/`)
+
 ## Documentation
 
 TermBeam has two layers of documentation that must stay in sync with code changes:
@@ -95,6 +118,16 @@ Preview docs locally: `pip install mkdocs-material && mkdocs serve`
 
 Changes to `docs/` or `mkdocs.yml` pushed to `main` auto-deploy to GitHub Pages.
 
+## CI and Publishing
+
+- Release workflow: `.github/workflows/release.yml` bumps version, updates `CHANGELOG.md`, tags, and publishes to npm.
+- `prepublishOnly` runs `npm test` before publish.
+- `postinstall` fixes `node-pty` prebuild permissions (spawn-helper).
+- Landing site (`landing/`) deploys via `.github/workflows/landing.yml`.
+- Docs deploy via `.github/workflows/pages.yml`.
+
+**IMPORTANT:** When asked to create a PR, open a PR, push to main, publish, release, or submit changes, **always use the `publish` skill**. It orchestrates the full workflow: local tests, lint, coverage, docs check, commit, push (or PR flow with proper branch naming), CI verification, and release. Do not manually run `gh pr create` or `git push origin main` — the skill handles all of this with the correct conventions.
+
 ## Demo Video
 
 The demo video lives in `demo-video/` and is built with Remotion 4 + TypeScript + React, using the remotion agent skill "npx skills add remotion-dev/skills".

.github/skills/publish/SKILL.md

@@ -36,7 +36,7 @@ Must exit cleanly. If it fails, stop and report.
 npm run test:coverage
 ```
 
-Coverage must meet the 80% threshold. If it drops below 80%, stop and report
+Coverage must meet the 92% threshold. If it drops below 80%, stop and report
 which files/areas lost coverage. The coverage summary is written to
 `coverage/coverage-summary.json` — you can inspect it for details.
 
@@ -58,6 +58,12 @@ Compare the changes against the documentation files. Check:
 - **`docs/getting-started.md`** — if installation or first-run steps changed.
   and any other docs files relevant to the changes.
 
+Use read-only subagents to verify documentation accuracy. Assign each subagent
+to a doc area (e.g., CLI/config, API/WebSocket, security, architecture).
+Each subagent should compare the code changes to the relevant docs and report
+any mismatches or missing updates. If any subagent flags an issue, update the
+docs before proceeding.
+
 If docs are outdated, update them before proceeding. Show the user what you updated.
 
 If the changes are purely UI/cosmetic (e.g., CSS, HTML template changes in `public/`),
@@ -88,9 +94,11 @@ If there are multiple types of changes, use the most significant one.
 
 - **PR flow:** If the user explicitly asked to create a PR:
   1. **Ensure an issue exists.** Every PR must reference an issue. If the
-     user mentioned an issue number, use it. If not, create one:
+     user mentioned an issue number, use it. Otherwise, verify that a matching
+     issue already exists or create one:
 
      ```bash
+     gh issue list --state open --search "<keywords>" --limit 5
      gh issue create --title "<short description>" --body "<brief context>"
      ```
 

README.md

@@ -72,6 +72,7 @@ termbeam -i                     # interactive setup wizard
 
 - **Terminal search** with regex, match count, and prev/next navigation
 - **Command palette** (Ctrl+K / Cmd+K) for quick access to all actions
+- **File upload** — send files from your phone to the session's working directory
 - **Completion notifications** — browser alerts when background commands finish
 - **12 color themes** with adjustable font size
 - **Port preview** — reverse-proxy a local web server through TermBeam

docs/api.md

@@ -328,6 +328,48 @@ Returned when the file's magic bytes don't match the declared `Content-Type` hea
 
 Maximum file size is 10 MB.
 
+#### `POST /api/sessions/:id/upload`
+
+Upload a file to a session's working directory. The request body is the raw file content. The filename is provided via the `X-Filename` header and sanitized server-side (path traversal sequences are stripped). Duplicate filenames are auto-renamed (e.g., `file (1).txt`).
+
+**Request headers:**
+
+- `Content-Type`: The file's MIME type (e.g., `application/octet-stream`)
+- `X-Filename`: Original filename (required)
+- `X-Target-Dir`: Override destination directory (optional, defaults to session cwd)
+
+**Response (200):**
+
+```json
+{ "name": "script.sh", "path": "/home/user/project/script.sh", "size": 1024 }
+```
+
+**Response (400):**
+
+```json
+{ "error": "Missing X-Filename header" }
+```
+
+```json
+{ "error": "Invalid filename" }
+```
+
+```json
+{ "error": "Empty file" }
+```
+
+**Response (404):**
+
+```json
+{ "error": "Session not found" }
+```
+
+**Response (413):**
+
+```json
+{ "error": "File too large (max 10 MB)" }
+```
+
 #### `GET /uploads/:id`
 
 Serve a previously uploaded file by its opaque ID. Requires authentication.

docs/index.md

@@ -36,6 +36,7 @@ Built for developers who need quick remote terminal access without the hassle of
 
 - **Terminal search** — <kbd>Ctrl+F</kbd> / <kbd>Cmd+F</kbd> with regex support
 - **Command palette** — <kbd>Ctrl+K</kbd> / <kbd>Cmd+K</kbd> for quick access to all actions
+- **File upload** — send files from your phone to the session's working directory via the command palette
 - **Command completion notifications** — browser alerts when commands finish in background tabs
 - **12 color themes** (dark, light, monokai, nord, dracula…) with adjustable font size
 - **Port preview** — reverse-proxy a local web server through TermBeam

docs/usage-guide.md

@@ -39,6 +39,14 @@ Once you've [started TermBeam](getting-started.md) and connected from your devic
 - Browse categorized actions: **Session**, **Search**, **View**, **Share**, **Notifications**, **System**
 - A quick way to discover all available features and shortcuts
 
+### File Upload
+
+- Open the **command palette** and select **Upload files** to send files from your phone (or any browser) to the active session's working directory
+- Select one or more files — a confirmation modal shows the file list with sizes and the destination directory
+- Use the **folder browser** to choose a different target directory
+- Files exceeding 10 MB are flagged and cannot be uploaded
+- After upload, a toast notification confirms the count and destination
+
 ### Notifications
 
 - Open the **command palette** (<kbd>Ctrl+K</kbd> / <kbd>Cmd+K</kbd>) and select **Toggle notifications** to enable **command completion notifications**

landing/index.html

@@ -288,6 +288,15 @@ <h3>Folder browser</h3>
               commands.
             </p>
           </div>
+
+          <div class="feature-card">
+            <div class="feature-icon-wrap">📤</div>
+            <h3>File upload</h3>
+            <p>
+              Upload files from your phone directly into the session's working directory. Multi-file
+              support with a confirmation dialog.
+            </p>
+          </div>
         </div>
       </div>
     </section>