feat: add update notification system

Adds automatic update checking that notifies users when a new version is available on npm, with install-method-aware update commands.

- Zero-dependency npm registry check with 24h disk cache
- CLI startup banner with non-blocking async check
- API endpoint GET /api/update-check with auth + rate limiting
- Web UI dismissable update banner on session manager page
- Check for updates button with Copy in About modal
- 39 tests with deterministic mocking
- Security hardening (sanitizeVersion, response size limit, bounded regex)
- Install method detection (npm/npx/yarn/pnpm)

Author: dorlugasigal

.github/copilot-instructions.md

@@ -3,7 +3,8 @@
 ## Build, Test, and Lint
 
 ```bash
-npm test                              # run all tests
+npm test                              # run all tests (output buffered until done)
+node --test test/*.test.js            # run all tests with streaming output (preferred for dev/CI agents)
 node --test test/auth.test.js         # run a single test file
 npm run test:coverage                 # tests + coverage (c8, 92% threshold)
 npm run lint                          # syntax-check with node --check
@@ -12,11 +13,13 @@ npm run dev                           # start with auto-generated password
 npm start                             # start with defaults
 ```
 
+> **Agent note:** Prefer `node --test test/*.test.js` over `npm test` when you need streaming output. The `npm test` script wraps `node --test` in `execFileSync` which buffers all output until completion — this makes it look like tests are hanging when they're actually running fine. The direct command gives real-time feedback.
+
 Pre-commit hooks (Husky + lint-staged) auto-format and syntax-check staged files.
 
 ### Testing Best Practices
 
-**Suite overview:** 464 tests, ~17s total. Tests run in parallel child processes via Node's built-in test runner. Most files run in <1s; `integration.test.js` (~17s) and `service.test.js` (~9s) are the slow outliers.
+**Suite overview:** 530+ tests, ~17s total. Tests run in parallel child processes via Node's built-in test runner. Most files run in <1s; `integration.test.js` (~17s) and `service.test.js` (~9s) are the slow outliers.
 
 **Slow tests and why:**
 

docs/api.md

@@ -273,6 +273,33 @@ Get the server version.
 { "version": "1.0.0" }
 ```
 
+#### `GET /api/update-check`
+
+Check if a newer version of TermBeam is available on npm. Results are cached for 24 hours.
+Requires authentication (session cookie or `Authorization: Bearer <password>`) when authentication is enabled. If the server is started with `--no-password`, this endpoint is accessible without authentication.
+
+**Query parameters:**
+
+| Parameter | Type    | Description                       |
+| --------- | ------- | --------------------------------- |
+| `force`   | boolean | Bypass cache and fetch fresh data |
+
+**Response:**
+
+```json
+{
+  "current": "1.10.2",
+  "latest": "1.11.0",
+  "updateAvailable": true,
+  "method": "npm",
+  "command": "npm install -g termbeam@latest"
+}
+```
+
+The `method` field indicates how TermBeam was installed (`npm`, `npx`, `yarn`, or `pnpm`) and `command` provides the appropriate update command.
+
+When no update is available or the check fails, `updateAvailable` is `false` and `latest` may be `null`.
+
 #### `GET /api/dirs?q=/path`
 
 List subdirectories for the folder browser.

public/index.html

@@ -197,6 +197,45 @@
         border: 1px solid rgba(128, 128, 128, 0.3);
       }
 
+      .update-banner {
+        margin: 12px 16px 0;
+        padding: 10px 14px;
+        background: var(--surface);
+        border: 1px solid var(--accent);
+        border-radius: 10px;
+        display: none;
+        align-items: center;
+        gap: 10px;
+        font-size: 13px;
+        color: var(--text);
+      }
+      .update-banner.visible {
+        display: flex;
+      }
+      .update-banner-text {
+        flex: 1;
+      }
+      .update-banner-text code {
+        font-size: 12px;
+        background: var(--border);
+        padding: 2px 6px;
+        border-radius: 4px;
+        word-break: break-all;
+      }
+      .update-banner-dismiss {
+        background: none;
+        border: none;
+        color: var(--text-dim);
+        cursor: pointer;
+        font-size: 18px;
+        line-height: 1;
+        padding: 0 2px;
+        flex-shrink: 0;
+      }
+      .update-banner-dismiss:hover {
+        color: var(--text);
+      }
+
       .sessions-list {
         padding: 16px;
         padding-bottom: calc(80px + env(safe-area-inset-bottom, 0px));
@@ -730,7 +769,8 @@
     <div class="header">
       <h1>📡 Term<span>Beam</span></h1>
       <p>
-        Beam your terminal to any device · <span id="version" style="color: var(--accent)"></span>
+        Beam your terminal to any device ·
+        <span id="version" style="color: var(--accent)"></span>
       </p>
       <button class="header-btn" id="share-btn" style="right: 96px; top: 16px" title="Share link">
         <svg
@@ -833,6 +873,23 @@ <h1>📡 Term<span>Beam</span></h1>
       </div>
     </div>
 
+    <div class="update-banner" id="update-banner">
+      <div class="update-banner-text">
+        <strong>Update available:</strong> <span id="update-versions"></span><br />
+        <span id="update-command-text"
+          >Run: <code id="update-command">npm install -g termbeam@latest</code></span
+        >
+      </div>
+      <button
+        class="update-banner-dismiss"
+        id="update-dismiss"
+        title="Dismiss"
+        aria-label="Dismiss update notification"
+      >
+        &times;
+      </button>
+    </div>
+
     <div class="sessions-list" id="sessions-list"></div>
     <button class="new-session" id="new-session-btn">+ New Session</button>
 
@@ -981,6 +1038,36 @@ <h3>
       const listEl = document.getElementById('sessions-list');
       const modal = document.getElementById('modal');
 
+      // Update notification
+      (async function checkUpdate() {
+        if (sessionStorage.getItem('update-dismissed')) return;
+        try {
+          const res = await fetch('/api/update-check');
+          if (!res.ok) return;
+          const info = await res.json();
+          if (info.updateAvailable && info.latest) {
+            const banner = document.getElementById('update-banner');
+            document.getElementById('update-versions').textContent =
+              'v' + info.current + ' \u2192 v' + info.latest;
+            if (info.command) {
+              const cmdEl = document.getElementById('update-command');
+              cmdEl.textContent = info.command;
+              if (info.method === 'npx') {
+                document.getElementById('update-command-text').textContent = 'Next time, run: ';
+                document.getElementById('update-command-text').appendChild(cmdEl);
+              }
+            }
+            banner.classList.add('visible');
+          }
+        } catch {
+          // Silent — update check is non-critical
+        }
+      })();
+      document.getElementById('update-dismiss').addEventListener('click', () => {
+        document.getElementById('update-banner').classList.remove('visible');
+        sessionStorage.setItem('update-dismissed', '1');
+      });
+
       function getActivityLabel(ts) {
         if (!ts) return '';
         const diff = (Date.now() - ts) / 1000;

public/terminal.html

@@ -4545,15 +4545,82 @@ <h3>
               box.innerHTML =
                 '<div style="font-size:24px;margin-bottom:8px;">⚡</div>' +
                 '<div style="font-size:16px;font-weight:600;color:var(--text);margin-bottom:4px;">TermBeam</div>' +
-                '<div style="font-size:13px;color:var(--text-secondary);margin-bottom:16px;">' +
+                '<div style="font-size:13px;color:var(--text-secondary);margin-bottom:12px;">' +
                 esc(ver) +
                 '</div>' +
                 '<div style="font-size:12px;color:var(--text-secondary);margin-bottom:16px;">Terminal in your browser, optimized for mobile.</div>' +
                 '<div style="display:flex;gap:16px;justify-content:center;margin-bottom:16px;">' +
                 '<a href="https://github.com/dorlugasigal/TermBeam" target="_blank" rel="noopener" style="color:var(--accent);font-size:12px;text-decoration:none;">GitHub</a>' +
                 '<a href="https://dorlugasigal.github.io/TermBeam/" target="_blank" rel="noopener" style="color:var(--accent);font-size:12px;text-decoration:none;">Docs</a>' +
                 '<a href="https://termbeam.pages.dev" target="_blank" rel="noopener" style="color:var(--accent);font-size:12px;text-decoration:none;">Website</a>' +
-                '</div>';
+                '</div>' +
+                '<div id="about-update-area" style="margin-bottom:12px;"></div>';
+              const updateArea = box.querySelector('#about-update-area');
+              const updateBtn = document.createElement('button');
+              updateBtn.textContent = 'Check for updates';
+              updateBtn.style.cssText =
+                'padding:6px 16px;border-radius:6px;border:1px solid var(--border);background:transparent;color:var(--text-secondary);font-size:12px;cursor:pointer;';
+              updateBtn.onclick = async () => {
+                updateBtn.textContent = 'Checking...';
+                updateBtn.disabled = true;
+                updateBtn.style.cursor = 'default';
+                try {
+                  const res = await fetch('/api/update-check?force=true');
+                  if (!res.ok) throw new Error();
+                  const info = await res.json();
+                  if (info.updateAvailable && info.latest) {
+                    const cmd = info.command || 'npm install -g termbeam@latest';
+                    updateArea.innerHTML = '';
+                    const status = document.createElement('div');
+                    status.style.cssText = 'font-size:12px;color:var(--accent);margin-bottom:8px;';
+                    status.textContent = 'v' + info.latest + ' available';
+                    updateArea.appendChild(status);
+                    const cmdRow = document.createElement('div');
+                    cmdRow.style.cssText =
+                      'display:flex;align-items:center;justify-content:center;gap:6px;';
+                    const cmdText = document.createElement('code');
+                    cmdText.textContent = cmd;
+                    cmdText.style.cssText =
+                      'font-size:11px;color:var(--accent);background:var(--bg);padding:4px 8px;border-radius:4px;border:1px solid var(--border);';
+                    const copyBtn = document.createElement('button');
+                    copyBtn.textContent = 'Copy';
+                    copyBtn.style.cssText =
+                      'padding:4px 10px;border-radius:4px;border:1px solid var(--accent);background:transparent;color:var(--accent);font-size:11px;cursor:pointer;';
+                    copyBtn.onclick = () => {
+                      const onSuccess = () => {
+                        copyBtn.textContent = 'Copied!';
+                        setTimeout(() => {
+                          copyBtn.textContent = 'Copy';
+                        }, 2000);
+                      };
+                      if (navigator.clipboard && navigator.clipboard.writeText) {
+                        navigator.clipboard
+                          .writeText(cmd)
+                          .then(onSuccess)
+                          .catch(() => {
+                            copyFallback(cmd);
+                            onSuccess();
+                          });
+                      } else {
+                        copyFallback(cmd);
+                        onSuccess();
+                      }
+                    };
+                    cmdRow.appendChild(cmdText);
+                    cmdRow.appendChild(copyBtn);
+                    updateArea.appendChild(cmdRow);
+                  } else {
+                    updateBtn.textContent = 'Up to date';
+                    updateBtn.style.color = '#4ec9b0';
+                    updateBtn.style.borderColor = '#4ec9b0';
+                  }
+                } catch {
+                  updateBtn.textContent = 'Check failed — try again';
+                  updateBtn.disabled = false;
+                  updateBtn.style.cursor = 'pointer';
+                }
+              };
+              updateArea.appendChild(updateBtn);
               const btn = document.createElement('button');
               btn.textContent = 'Close';
               btn.style.cssText =

src/routes.js

@@ -87,6 +87,29 @@ function setupRoutes(app, { auth, sessions, config, state }) {
     res.json({ version: getVersion() });
   });
 
+  // Update check API
+  app.get('/api/update-check', apiRateLimit, auth.middleware, async (req, res) => {
+    const { checkForUpdate, detectInstallMethod } = require('./update-check');
+    const force = req.query.force === 'true';
+
+    try {
+      const info = await checkForUpdate({ currentVersion: config.version, force });
+      const installInfo = detectInstallMethod();
+      state.updateInfo = { ...info, ...installInfo };
+      res.json(state.updateInfo);
+    } catch {
+      const installInfo = detectInstallMethod();
+      const fallback = {
+        current: config.version,
+        latest: null,
+        updateAvailable: false,
+        ...installInfo,
+      };
+      state.updateInfo = fallback;
+      res.json(fallback);
+    }
+  });
+
   // Share token auto-login middleware: validates ?ott= param, sets session cookie, redirects to clean URL
   function autoLogin(req, res, next) {
     const { ott } = req.query;

src/server.js

@@ -16,6 +16,7 @@ const { setupWebSocket } = require('./websocket');
 const { startTunnel, cleanupTunnel, findDevtunnel } = require('./tunnel');
 const { createPreviewProxy } = require('./preview');
 const { writeConnectionConfig, removeConnectionConfig } = require('./resume');
+const { checkForUpdate, detectInstallMethod } = require('./update-check');
 
 // --- Helpers ---
 function getLocalIP() {
@@ -73,7 +74,7 @@ function createTermBeamServer(overrides = {}) {
   const server = http.createServer(app);
   const wss = new WebSocketServer({ server, path: '/ws', maxPayload: 1 * 1024 * 1024 });
 
-  const state = { shareBaseUrl: null };
+  const state = { shareBaseUrl: null, updateInfo: null };
   app.use('/preview', auth.middleware, createPreviewProxy());
   setupRoutes(app, { auth, sessions, config, state });
   setupWebSocket(wss, { auth, sessions });
@@ -273,6 +274,36 @@ function createTermBeamServer(overrides = {}) {
         );
         console.log('');
 
+        // Non-blocking update check — runs after banner, never delays startup.
+        // Skip under the Node test runner to avoid network requests in tests.
+        // Accept any version containing a semver-like pattern (including dev builds).
+        const versionParts = config.version.match(/(\d{1,10})\.(\d{1,10})\.(\d{1,10})/);
+        if (versionParts && !process.env.NODE_TEST_CONTEXT && !process.argv.includes('--test')) {
+          const installInfo = detectInstallMethod();
+          checkForUpdate({ currentVersion: config.version })
+            .then((info) => {
+              state.updateInfo = { ...info, ...installInfo };
+              if (info.updateAvailable) {
+                const yl = '\x1b[33m';
+                const gn2 = '\x1b[38;5;114m';
+                const dm = '\x1b[2m';
+                console.log('');
+                console.log(
+                  `  ${yl}Update available:${rs} ${dm}${info.current}${rs} → ${gn2}${info.latest}${rs}`,
+                );
+                if (installInfo.method === 'npx') {
+                  console.log(`  Next time, run: ${gn2}npx termbeam@latest${rs}`);
+                } else {
+                  console.log(`  Run: ${gn2}${installInfo.command}${rs}`);
+                }
+                console.log('');
+              }
+            })
+            .catch(() => {
+              // Silent failure — update check is non-critical
+            });
+        }
+
         resolve({ url: `http://localhost:${actualPort}`, defaultId });
       });
     });