You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat: docs accuracy, side panel UX, SW font caching, test coverage (#22)
## Summary
Quality and polish improvements across documentation, UI, caching, and
test coverage.
### Documentation
- Fixed inaccurate \SHELL\ env var default (\/bin/zsh\ → \/bin/sh\,
documented as fallback)
- Added missing \COMSPEC\ (Windows) env var documentation
- Fixed \--password\ flag docs to include \--password=<pw>\ syntax
- Updated prerequisites: Windows native support (not just WSL)
- Added \cmd\ field to \GET /api/shells\ response schema
- Architecture: added missing files (sw.js, manifest.json, icons/, 3
test files)
- Architecture: expanded module descriptions (cli.js, sessions.js,
websocket.js, routes.js)
- README: updated env var list and Windows support
### Side Panel (mobile)
- Widened from 320px → 380px for better readability
- Added **close (×) button** on each session card to delete sessions
directly from sidebar
- Added **\"+ New Session\"** button pinned at the bottom
- Added \safe-area-inset\ padding (top, left, bottom) for iPhone PWA
rounded corners
### Service Worker
- CDN font files (NerdFont \.ttf\ from jsdelivr) are now cached with a
cache-first strategy
- Previously skipped as external-origin requests — fonts re-downloaded
on every reconnect
- Cache version bumped to v2
### Test Coverage
- **79.22% → 89.6% statements** (427/539 → 483/539)
- **90.47% → 95.83% functions**
- \shells.js\: 49% → 96% — added mocked Unix shell detection tests
- \cli.js\: 60% → 85% — added env var, printHelp, shell args, flag
override tests
- Exported \detectUnixShells\/\detectWindowsShells\ for testability
### All 83 tests passing ✓
| `color` | string | Hex color assigned to the session |
72
+
| `lastActivity` | number | Unix timestamp (ms) of the last PTY output |
66
73
```
67
74
68
75
#### `POST /api/sessions`
@@ -77,11 +84,12 @@ Create a new session.
77
84
"shell": "/bin/bash",
78
85
"args": ["-l"],
79
86
"cwd": "/home/user",
80
-
"initialCommand": "htop"
87
+
"initialCommand": "htop",
88
+
"color": "#4ade80"
81
89
}
82
90
```
83
91
84
-
All fields are optional. If `initialCommand` is provided, it will be sent to the shell after startup.
92
+
All fields are optional. If `initialCommand` is provided, it will be sent to the shell after startup. If `color` is omitted, a color is assigned automatically from a built-in palette.
85
93
86
94
**Response:**
87
95
@@ -92,6 +100,35 @@ All fields are optional. If `initialCommand` is provided, it will be sent to the
92
100
}
93
101
```
94
102
103
+
#### `PATCH /api/sessions/:id`
104
+
105
+
Update session properties.
106
+
107
+
**Request:**
108
+
109
+
```json
110
+
{
111
+
"color": "#f87171",
112
+
"name": "renamed-session"
113
+
}
114
+
```
115
+
116
+
All fields are optional.
117
+
118
+
**Response (200):**
119
+
120
+
```json
121
+
{ "ok": true }
122
+
```
123
+
124
+
**Response (404):**
125
+
126
+
```json
127
+
{ "error": "not found" }
128
+
```
129
+
130
+
---
131
+
95
132
#### `DELETE /api/sessions/:id`
96
133
97
134
Kill and remove a session.
@@ -117,13 +154,20 @@ List available shells on the host system.
Copy file name to clipboardExpand all lines: docs/architecture.md
+13-7Lines changed: 13 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,11 +17,17 @@ termbeam/
17
17
│ └── version.js # Smart version detection
18
18
├── public/
19
19
│ ├── index.html # Session manager (mobile UI)
20
-
│ └── terminal.html # Terminal view (xterm.js)
20
+
│ ├── terminal.html # Terminal view (xterm.js)
21
+
│ ├── sw.js # Service worker (PWA caching)
22
+
│ ├── manifest.json # Web app manifest
23
+
│ └── icons/ # PWA icons
21
24
├── test/
22
-
│ ├── cli.test.js
23
25
│ ├── auth.test.js
24
-
│ └── sessions.test.js
26
+
│ ├── cli.test.js
27
+
│ ├── sessions.test.js
28
+
│ ├── shells.test.js
29
+
│ ├── version.test.js
30
+
│ └── websocket.test.js
25
31
├── docs/ # MkDocs documentation
26
32
├── package.json
27
33
└── mkdocs.yml
@@ -35,23 +41,23 @@ Wires all modules together. Creates the Express app, HTTP server, WebSocket serv
35
41
36
42
### `cli.js` — CLI Interface
37
43
38
-
Parses command-line arguments and environment variables. Returns a config object used by all other modules.
44
+
Parses command-line arguments and environment variables. Returns a config object used by all other modules. Includes platform-specific shell auto-detection: on Windows it walks the process tree (via `wmic`) looking for PowerShell or cmd.exe; on Unix it inspects the parent process via `ps` and falls back to `$SHELL` or `/bin/sh`.
39
45
40
46
### `auth.js` — Authentication
41
47
42
48
Factory function `createAuth(password)` returns an object with middleware, token management, rate limiting, and the login page HTML.
43
49
44
50
### `sessions.js` — Session Manager
45
51
46
-
`SessionManager` class wraps the PTY lifecycle. Handles spawning, tracking, listing, and cleaning up terminal sessions.
52
+
`SessionManager` class wraps the PTY lifecycle. Handles spawning, tracking, listing, updating, and cleaning up terminal sessions. Each session has an auto-assigned color, tracks `lastActivity` timestamps, a `createdAt` timestamp, and supports live updates via the `update()` method. Sessions maintain a scrollback buffer (capped at 200 KB) that is sent to newly connecting clients, and track a `clients` Set of active WebSocket connections. Supports an optional `initialCommand` that is written to the PTY shortly after spawn.
47
53
48
54
### `routes.js` — HTTP Routes
49
55
50
-
Registers all Express routes: login page, auth API, session CRUD, shell detection, directory browser, version endpoint.
56
+
Registers all Express routes: login page (`GET /login`), auth API, session CRUD (including `PATCH` for updating session color/name), shell detection, directory browser, version endpoint. The `POST /api/sessions` endpoint accepts optional `shell`, `args`, `cwd`, `initialCommand`, and `color` parameters.
Handles real-time communication: WebSocket-level authentication (password or token), session attachment, terminal I/O forwarding, and resize events. When multiple clients are connected to the same session, the PTY is resized to the minimum dimensions across all clients.
|`--password <pw>`| Set access password (also accepts `--password=<pw>`)| None |
8
8
|`--generate-password`| Auto-generate a secure password | — |
9
9
|`--tunnel`| Create an ephemeral devtunnel URL | Off |
10
10
|`--persisted-tunnel`| Create a reusable devtunnel URL (stable across restarts) | Off |
@@ -20,11 +20,15 @@
20
20
|`PORT`| Server port |`3456`|
21
21
|`TERMBEAM_PASSWORD`| Access password | None |
22
22
|`TERMBEAM_CWD`| Default working directory | Current directory |
23
-
|`SHELL`| Default shell |`/bin/zsh`|
23
+
|`SHELL`| Fallback shell on Unix (used only if auto-detection fails) |`/bin/sh`|
24
+
|`COMSPEC`| Fallback shell on Windows (used only if auto-detection fails) |`cmd.exe`|
24
25
25
26
!!! note
26
27
CLI flags take precedence over environment variables.
27
28
29
+
!!! info "Shell Auto-Detection"
30
+
TermBeam auto-detects your current shell by inspecting the parent process tree. The `SHELL` (Unix) and `COMSPEC` (Windows) environment variables are only used as fallbacks when detection fails.
31
+
28
32
!!! info "Legacy Variables"
29
33
The environment variables `PTY_PASSWORD` and `PTY_CWD` are also supported as fallbacks for `TERMBEAM_PASSWORD` and `TERMBEAM_CWD` respectively.
0 commit comments