feat(tunnel): add findDevtunnel function and improve error handling for tunnel mode

Author: dorlugasigal

src/server.js

@@ -12,7 +12,7 @@ const { createAuth } = require('./auth');
 const { SessionManager } = require('./sessions');
 const { setupRoutes, cleanupUploadedFiles } = require('./routes');
 const { setupWebSocket } = require('./websocket');
-const { startTunnel, cleanupTunnel } = require('./tunnel');
+const { startTunnel, cleanupTunnel, findDevtunnel } = require('./tunnel');
 
 // --- Helpers ---
 function getLocalIP() {
@@ -75,6 +75,29 @@ function createTermBeamServer(overrides = {}) {
   }
 
   function start() {
+    // Fail early if tunnel mode is on but devtunnel CLI is not installed
+    if (config.useTunnel && !findDevtunnel()) {
+      log.error('❌ devtunnel CLI is not installed.');
+      log.error('');
+      log.error('  TermBeam uses tunnels by default for remote access.');
+      log.error('  Install the Azure Dev Tunnels CLI, or use --no-tunnel for LAN-only mode.');
+      log.error('');
+      log.error('  Install it:');
+      log.error('    Windows:  winget install Microsoft.devtunnel');
+      log.error(
+        '             or: Invoke-WebRequest -Uri https://aka.ms/TunnelsCliDownload/win-x64 -OutFile devtunnel.exe',
+      );
+      log.error('    macOS:    brew install --cask devtunnel');
+      log.error('    Linux:    curl -sL https://aka.ms/DevTunnelCliInstall | bash');
+      log.error('');
+      log.error('  Then restart your terminal and try again.');
+      log.error(
+        '  Docs: https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started',
+      );
+      log.error('');
+      process.exit(1);
+    }
+
     return new Promise((resolve) => {
       server.listen(config.port, config.host, async () => {
         const ip = getLocalIP();

src/tunnel.js

@@ -89,7 +89,8 @@ async function startTunnel(port, options = {}) {
   if (!found) {
     log.error('❌ devtunnel CLI is not installed.');
     log.error('');
-    log.error('  The --tunnel flag requires the Azure Dev Tunnels CLI.');
+    log.error('  TermBeam uses tunnels by default for remote access.');
+    log.error('  Install the Azure Dev Tunnels CLI, or use --no-tunnel for LAN-only mode.');
     log.error('');
     log.error('  Install it:');
     log.error('    Windows:  winget install Microsoft.devtunnel');
@@ -120,19 +121,24 @@ async function startTunnel(port, options = {}) {
     } catch {}
 
     if (!loggedIn) {
-      log.info('devtunnel not logged in, launching login...');
-      log.info('A browser window will open for authentication.');
+      log.info('devtunnel not logged in, launching browser login (30s timeout)...');
       try {
-        execFileSync(devtunnelCmd, ['user', 'login'], { stdio: 'inherit' });
-      } catch (loginErr) {
-        log.error('');
-        log.error('  DevTunnel login failed. To use tunnels, run:');
-        log.error('    devtunnel user login');
-        log.error('');
-        log.error('  Or start without a tunnel:');
-        log.error('    termbeam --no-tunnel');
-        log.error('');
-        return null;
+        execFileSync(devtunnelCmd, ['user', 'login'], { stdio: 'inherit', timeout: 30000 });
+      } catch {
+        log.info('Browser login failed or unavailable, falling back to device code flow...');
+        log.info('A code will be displayed — open the URL on any device to authenticate.');
+        try {
+          execFileSync(devtunnelCmd, ['user', 'login', '-d'], { stdio: 'inherit' });
+        } catch (loginErr) {
+          log.error('');
+          log.error('  DevTunnel login failed. To use tunnels, run:');
+          log.error('    devtunnel user login');
+          log.error('');
+          log.error('  Or start without a tunnel:');
+          log.error('    termbeam --no-tunnel');
+          log.error('');
+          return null;
+        }
       }
     }
 
@@ -257,4 +263,4 @@ function cleanupTunnel() {
   }
 }
 
-module.exports = { startTunnel, cleanupTunnel };
+module.exports = { startTunnel, cleanupTunnel, findDevtunnel };