termbeam 1.12.5 → 1.13.1

package/src/server/auth.js

@@ -294,6 +294,7 @@ function createAuth(password) {
   // Periodically clean up expired tokens and stale rate-limit entries
   const cleanupInterval = setInterval(
     () => {
+      log.debug('Token cleanup: removing expired auth and share tokens');
       const now = Date.now();
       for (const [token, expiry] of tokens) {
         if (now > expiry) tokens.delete(token);
@@ -339,6 +340,7 @@ function createAuth(password) {
   function generateToken() {
     const token = crypto.randomBytes(32).toString('hex');
     tokens.set(token, Date.now() + 24 * 60 * 60 * 1000);
+    log.debug('Auth token generated (24h expiry)');
     return token;
   }
 

package/src/server/index.js

@@ -84,6 +84,7 @@ function createTermBeamServer(overrides = {}) {
   function shutdown() {
     if (shuttingDown) return;
     shuttingDown = true;
+    log.info('Shutdown initiated');
     auth.cleanup();
     sessions.shutdown();
     cleanupUploadedFiles();
@@ -231,6 +232,7 @@ function createTermBeamServer(overrides = {}) {
             publicUrl = tunnel.url;
             state.shareBaseUrl = publicUrl;
           } else {
+            log.warn('Tunnel failed to start, falling back to LAN-only');
             console.log('  ⚠️  Tunnel failed to start. Using LAN only.');
           }
         }
@@ -322,18 +324,22 @@ module.exports = { createTermBeamServer, getLocalIP };
 // Auto-start when run directly (e.g. `node src/server.js`)
 if (require.main === module) {
   const instance = createTermBeamServer();
+  const log = require('../utils/logger');
 
   process.on('SIGINT', () => {
+    log.info('Received SIGINT signal');
     console.log('\n[termbeam] Shutting down...');
     instance.shutdown();
     setTimeout(() => process.exit(0), 500).unref();
   });
   process.on('SIGTERM', () => {
+    log.info('Received SIGTERM signal');
     console.log('\n[termbeam] Shutting down...');
     instance.shutdown();
     setTimeout(() => process.exit(0), 500).unref();
   });
   process.on('uncaughtException', (err) => {
+    log.error(`Uncaught exception: ${err.message}`);
     console.error('[termbeam] Uncaught exception:', err.message);
     cleanupTunnel();
     process.exit(1);

package/src/server/preview.js

@@ -26,6 +26,7 @@ function createPreviewProxy() {
   function proxyRequest(req, res) {
     const port = Number(req.params.port);
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      log.warn(`Preview proxy: invalid port ${req.params.port} rejected`);
       return res
         .status(400)
         .json({ error: 'Invalid port: must be an integer between 1 and 65535' });
@@ -87,6 +88,7 @@ function createPreviewProxy() {
     });
 
     proxyReq.setTimeout(PROXY_TIMEOUT, () => {
+      log.warn(`Preview proxy: request to port ${port} timed out after ${PROXY_TIMEOUT}ms`);
       proxyReq.destroy();
       if (!res.headersSent) {
         res.status(504).json({ error: 'Gateway timeout: upstream server did not respond in time' });

package/src/server/routes.js

@@ -83,12 +83,14 @@ function setupRoutes(app, { auth, sessions, config, state }) {
 
   // Version API
   app.get('/api/version', (_req, res) => {
+    log.debug('Version requested');
     const { getVersion } = require('../utils/version');
     res.json({ version: getVersion() });
   });
 
   // Update check API
   app.get('/api/update-check', apiRateLimit, auth.middleware, async (req, res) => {
+    log.debug('Update check requested');
     const { checkForUpdate, detectInstallMethod } = require('../utils/update-check');
     const force = req.query.force === 'true';
 
@@ -97,7 +99,8 @@ function setupRoutes(app, { auth, sessions, config, state }) {
       const installInfo = detectInstallMethod();
       state.updateInfo = { ...info, ...installInfo };
       res.json(state.updateInfo);
-    } catch {
+    } catch (err) {
+      log.warn(`Update check failed: ${err.message}`);
       const installInfo = detectInstallMethod();
       const fallback = {
         current: config.version,
@@ -144,6 +147,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
 
   // Share token — generates a temporary share token for the share button
   app.get('/api/share-token', auth.middleware, (req, res) => {
+    log.debug('Share token requested');
     if (!auth.password) return res.status(404).json({ error: 'auth disabled' });
     const shareToken = auth.generateShareToken();
     const base = (state && state.shareBaseUrl) || `${req.protocol}://${req.get('host')}`;
@@ -152,6 +156,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
 
   // Session API
   app.get('/api/sessions', apiRateLimit, auth.middleware, (_req, res) => {
+    log.debug('Sessions list requested');
     res.json(sessions.list());
   });
 
@@ -163,6 +168,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
       const availableShells = detectShells();
       const isValid = availableShells.some((s) => s.path === shell || s.cmd === shell);
       if (!isValid) {
+        log.warn(`Session creation failed: invalid shell "${shell}"`);
         return res.status(400).json({ error: 'Invalid shell' });
       }
     }
@@ -170,6 +176,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
     // Validate args field — must be an array of strings
     if (shellArgs !== undefined) {
       if (!Array.isArray(shellArgs) || !shellArgs.every((a) => typeof a === 'string')) {
+        log.warn('Session creation failed: args must be an array of strings');
         return res.status(400).json({ error: 'args must be an array of strings' });
       }
     }
@@ -177,6 +184,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
     // Validate initialCommand field — must be a string
     if (initialCommand !== undefined && initialCommand !== null) {
       if (typeof initialCommand !== 'string') {
+        log.warn('Session creation failed: initialCommand must be a string');
         return res.status(400).json({ error: 'initialCommand must be a string' });
       }
     }
@@ -184,13 +192,16 @@ function setupRoutes(app, { auth, sessions, config, state }) {
     // Validate cwd field
     if (cwd) {
       if (!path.isAbsolute(cwd)) {
+        log.warn(`Session creation failed: cwd must be an absolute path (got "${cwd}")`);
         return res.status(400).json({ error: 'cwd must be an absolute path' });
       }
       try {
         if (!fs.statSync(cwd).isDirectory()) {
+          log.warn(`Session creation failed: cwd is not a directory (${cwd})`);
           return res.status(400).json({ error: 'cwd is not a directory' });
         }
       } catch {
+        log.warn(`Session creation failed: cwd does not exist (${cwd})`);
         return res.status(400).json({ error: 'cwd does not exist' });
       }
     }
@@ -216,6 +227,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
 
   // Available shells
   app.get('/api/shells', auth.middleware, (_req, res) => {
+    log.debug('Available shells requested');
     const shells = detectShells();
     const ds = config.defaultShell;
     const match = shells.find((s) => s.cmd === ds || s.path === ds || s.name === ds);
@@ -223,6 +235,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
   });
 
   app.get('/api/sessions/:id/detect-port', auth.middleware, (req, res) => {
+    log.debug(`Port detection requested for session ${req.params.id}`);
     const session = sessions.get(req.params.id);
     if (!session) return res.status(404).json({ error: 'not found' });
 
@@ -236,6 +249,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
     }
 
     if (lastPort !== null) {
+      log.debug(`Port detected for session ${req.params.id}: ${lastPort}`);
       res.json({ detected: true, port: lastPort });
     } else {
       res.json({ detected: false });
@@ -244,8 +258,10 @@ function setupRoutes(app, { auth, sessions, config, state }) {
 
   app.delete('/api/sessions/:id', auth.middleware, (req, res) => {
     if (sessions.delete(req.params.id)) {
+      log.info(`Session deleted: ${req.params.id}`);
       res.status(204).end();
     } else {
+      log.warn(`Session delete failed: not found (${req.params.id})`);
       res.status(404).json({ error: 'not found' });
     }
   });
@@ -256,14 +272,17 @@ function setupRoutes(app, { auth, sessions, config, state }) {
     if (color !== undefined) updates.color = color;
     if (name !== undefined) updates.name = name;
     if (sessions.update(req.params.id, updates)) {
+      log.info(`Session updated: ${req.params.id}`);
       res.json({ ok: true });
     } else {
+      log.warn(`Session update failed: not found (${req.params.id})`);
       res.status(404).json({ error: 'not found' });
     }
   });
 
   // Image upload
   app.post('/api/upload', auth.middleware, (req, res) => {
+    log.debug('Image upload started');
     const contentType = req.headers['content-type'] || '';
     if (!contentType.startsWith('image/')) {
       log.warn(`Upload rejected: invalid content-type "${contentType}"`);
@@ -334,6 +353,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
 
   // General file upload to a session's working directory
   app.post('/api/sessions/:id/upload', apiRateLimit, auth.middleware, (req, res) => {
+    log.debug(`File upload started for session ${req.params.id}`);
     const session = sessions.get(req.params.id);
     if (!session) {
       return res.status(404).json({ error: 'Session not found' });
@@ -440,6 +460,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
 
   // Directory listing for folder browser
   app.get('/api/dirs', apiRateLimit, auth.middleware, (req, res) => {
+    log.debug(`Directory listing requested: ${req.query.q || config.cwd}`);
     const query = req.query.q || config.cwd + path.sep;
     const endsWithSep = query.endsWith('/') || query.endsWith('\\');
     const dir = path.resolve(endsWithSep ? query : path.dirname(query));
@@ -453,13 +474,15 @@ function setupRoutes(app, { auth, sessions, config, state }) {
         .slice(0, 50)
         .map((e) => path.join(dir, e.name));
       res.json({ base: dir, dirs });
-    } catch {
+    } catch (err) {
+      log.warn(`Directory listing failed: ${err.message}`);
       res.json({ base: dir, dirs: [] });
     }
   });
 }
 
 function cleanupUploadedFiles() {
+  log.debug(`Cleaning up ${uploadedFiles.size} uploaded files`);
   for (const [_id, filepath] of uploadedFiles) {
     try {
       if (fs.existsSync(filepath)) {

package/src/server/sessions.js

@@ -15,17 +15,20 @@ function getCachedGitInfo(sessionId, pid, originalCwd) {
   const now = Date.now();
   const cached = _gitCache.get(sessionId);
   if (cached && now - cached.ts < GIT_CACHE_TTL) {
+    log.debug(`Git cache hit for session ${sessionId}`);
     return { cwd: cached.cwd, git: cached.git };
   }
 
   // Always refresh asynchronously to avoid blocking the event loop.
   // Return stale data if available, or null on first call.
+  log.debug(`Git cache miss for session ${sessionId}, scheduling refresh`);
   scheduleGitRefresh(sessionId, pid, originalCwd);
   if (cached) return { cwd: cached.cwd, git: cached.git };
   return { cwd: originalCwd, git: null };
 }
 
 function scheduleGitRefresh(sessionId, pid, originalCwd) {
+  log.debug(`Scheduling git refresh for session ${sessionId}`);
   // Mark as refreshing to prevent duplicate refreshes
   const cached = _gitCache.get(sessionId);
   if (cached && cached._refreshing) return;
@@ -61,6 +64,7 @@ function scheduleGitRefresh(sessionId, pid, originalCwd) {
     }
     const git = getGitInfo(liveCwd);
     _gitCache.set(sessionId, { cwd: liveCwd, git, ts: Date.now() });
+    log.debug(`Git refresh complete for session ${sessionId} (cwd=${liveCwd})`);
   });
 }
 
@@ -97,14 +101,17 @@ class SessionManager {
       /[;&|`$(){}\[\]!#~]/.test(shell) ||
       (!path.isAbsolute(shell) && !shell.match(/^[a-zA-Z0-9._-]+(\.exe)?$/))
     ) {
+      log.warn(`Invalid shell rejected: ${shell}`);
       throw new Error('Invalid shell');
     }
 
     // Defense-in-depth: validate args and initialCommand types
     if (!Array.isArray(args) || !args.every((a) => typeof a === 'string')) {
+      log.warn(`Invalid args rejected: ${JSON.stringify(args)}`);
       throw new Error('args must be an array of strings');
     }
     if (initialCommand !== null && typeof initialCommand !== 'string') {
+      log.warn(`Invalid initialCommand rejected: ${typeof initialCommand}`);
       throw new Error('initialCommand must be a string');
     }
 
@@ -112,6 +119,7 @@ class SessionManager {
     if (!color) {
       color = SESSION_COLORS[this.sessions.size % SESSION_COLORS.length];
     }
+    log.debug(`Spawning PTY: shell=${shell}, args=[${args.length} items], cwd=${cwd}`);
     const ptyProcess = pty.spawn(shell, args, {
       name: 'xterm-256color',
       cols,
@@ -122,6 +130,7 @@ class SessionManager {
 
     // Send initial command once the shell is ready
     if (initialCommand) {
+      log.debug(`Scheduling initialCommand for session ${id} (${initialCommand.length} chars)`);
       setTimeout(() => ptyProcess.write(initialCommand + '\r'), 300);
     }
 
@@ -177,6 +186,7 @@ class SessionManager {
       }
       // High/low water scrollback cap: trim to 500k chars when buffer exceeds 1,000,000 chars
       if (session.scrollbackBuf.length > 1000000) {
+        log.debug(`Trimming scrollback buffer from ${session.scrollbackBuf.length} to 500k chars`);
         let buf = session.scrollbackBuf.slice(-500000);
         // Advance to first newline to avoid starting mid-line
         const nlIdx = buf.indexOf('\n');
@@ -211,8 +221,18 @@ class SessionManager {
   update(id, fields) {
     const s = this.sessions.get(id);
     if (!s) return false;
-    if (fields.color !== undefined) s.color = fields.color;
-    if (fields.name !== undefined) s.name = fields.name;
+    const changes = [];
+    if (fields.color !== undefined) {
+      s.color = fields.color;
+      changes.push(`color=${fields.color}`);
+    }
+    if (fields.name !== undefined) {
+      s.name = fields.name;
+      changes.push(`name=${fields.name}`);
+    }
+    if (changes.length > 0) {
+      log.debug(`Session ${id} updated: ${changes.join(', ')}`);
+    }
     return true;
   }
 
@@ -242,15 +262,17 @@ class SessionManager {
         git,
       });
     }
+    log.debug(`Listing ${list.length} session(s)`);
     return list;
   }
 
   shutdown() {
+    log.info(`Shutting down ${this.sessions.size} session(s)`);
     for (const [_id, s] of this.sessions) {
       try {
         s.pty.kill();
-      } catch {
-        /* ignore */
+      } catch (err) {
+        log.warn(`Failed to kill session ${_id}: ${err.message}`);
       }
     }
     this.sessions.clear();

package/src/server/websocket.js

@@ -54,6 +54,7 @@ function recalcPtySize(session) {
   if (minCols === session._lastCols && minRows === session._lastRows) return;
   session._lastCols = minCols;
   session._lastRows = minRows;
+  log.debug(`PTY resized to ${minCols}×${minRows}`);
   session.pty.resize(minCols, minRows);
 }
 
@@ -177,6 +178,7 @@ function setupWebSocket(wss, { auth, sessions }) {
         } else if (msg.type === 'resize') {
           const cols = Math.floor(msg.cols);
           const rows = Math.floor(msg.rows);
+          log.debug(`Client resize request: ${cols}×${rows}`);
           if (cols > 0 && cols <= 500 && rows > 0 && rows <= 200) {
             ws._dims = { cols, rows };
             ws._lastActivity = Date.now();

package/src/utils/git.js

@@ -1,5 +1,6 @@
 const { execSync } = require('child_process');
 const path = require('path');
+const log = require('./logger');
 
 function git(cmd, cwd) {
   return execSync(`git ${cmd}`, { cwd, stdio: 'pipe', timeout: 3000 }).toString().trim();
@@ -9,6 +10,7 @@ function getGitInfo(cwd) {
   try {
     git('rev-parse --is-inside-work-tree', cwd);
   } catch {
+    log.debug(`Not a git repository: ${cwd}`);
     return null;
   }
 
@@ -59,6 +61,7 @@ function getGitInfo(cwd) {
     /* ignore */
   }
 
+  log.debug(`Git info resolved for ${cwd}`);
   return result;
 }
 

package/src/utils/update-check.js

@@ -3,6 +3,7 @@ const http = require('http');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const log = require('./logger');
 
 const PACKAGE_NAME = 'termbeam';
 const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
@@ -114,9 +115,11 @@ function sanitizeVersion(v) {
 function fetchLatestVersion(registryUrl) {
   const url = registryUrl || REGISTRY_URL;
   const client = url.startsWith('https') ? https : http;
+  log.debug('Fetching latest version from npm registry');
   return new Promise((resolve) => {
     const req = client.get(url, { timeout: REQUEST_TIMEOUT_MS }, (res) => {
       if (res.statusCode !== 200) {
+        log.warn(`Registry returned HTTP ${res.statusCode}`);
         res.resume();
         resolve(null);
         return;
@@ -154,8 +157,12 @@ function fetchLatestVersion(registryUrl) {
     });
     // Unref so a pending update check can't delay process exit
     req.on('socket', (socket) => socket.unref());
-    req.on('error', () => resolve(null));
+    req.on('error', (err) => {
+      log.debug(`Network error checking updates: ${err.message}`);
+      resolve(null);
+    });
     req.on('timeout', () => {
+      log.warn('Update check timed out');
       req.destroy();
       resolve(null);
     });
@@ -170,6 +177,7 @@ function fetchLatestVersion(registryUrl) {
  * @returns {Promise<{current: string, latest: string|null, updateAvailable: boolean}>}
  */
 async function checkForUpdate({ currentVersion, force = false } = {}) {
+  log.debug(`Update check: current=${currentVersion}`);
   if (!currentVersion) {
     return { current: 'unknown', latest: null, updateAvailable: false };
   }
@@ -180,6 +188,7 @@ async function checkForUpdate({ currentVersion, force = false } = {}) {
     if (cache && Date.now() - cache.checkedAt < CACHE_TTL_MS) {
       const cachedLatest = typeof cache.latest === 'string' ? sanitizeVersion(cache.latest) : null;
       if (cachedLatest && /^\d+\.\d+\.\d+$/.test(cachedLatest)) {
+        log.debug('Using cached update check result');
         return {
           current: currentVersion,
           latest: cachedLatest,
@@ -198,10 +207,17 @@ async function checkForUpdate({ currentVersion, force = false } = {}) {
   // Cache the result
   writeCache(latest);
 
+  const updateAvailable = isNewerVersion(currentVersion, latest);
+  log.debug(
+    updateAvailable
+      ? `Update available: ${currentVersion} → ${latest}`
+      : `Already on latest version: ${currentVersion}`,
+  );
+
   return {
     current: currentVersion,
     latest,
-    updateAvailable: isNewerVersion(currentVersion, latest),
+    updateAvailable,
   };
 }
 
@@ -212,19 +228,23 @@ async function checkForUpdate({ currentVersion, force = false } = {}) {
 function detectInstallMethod() {
   // npx / npm exec — npm sets npm_command=exec
   if (process.env.npm_command === 'exec') {
+    log.debug('Install method: npx');
     return { method: 'npx', command: 'npx termbeam@latest' };
   }
 
   // Detect package manager from npm_execpath (set during npm/yarn/pnpm lifecycle)
   const execPath = process.env.npm_execpath || '';
   if (execPath.includes('yarn')) {
+    log.debug('Install method: yarn');
     return { method: 'yarn', command: 'yarn global add termbeam@latest' };
   }
   if (execPath.includes('pnpm')) {
+    log.debug('Install method: pnpm');
     return { method: 'pnpm', command: 'pnpm add -g termbeam@latest' };
   }
 
   // Default: npm global install
+  log.debug('Install method: npm');
   return { method: 'npm', command: 'npm install -g termbeam@latest' };
 }
 

package/src/utils/version.js

@@ -1,5 +1,6 @@
 const path = require('path');
 const { execSync } = require('child_process');
+const log = require('./logger');
 
 function getVersion() {
   const pkg = require(path.join(__dirname, '..', '..', 'package.json'));
@@ -7,7 +8,12 @@ function getVersion() {
 
   // If installed via npm (global or npx), use the package version as-is
   if (process.env.npm_package_version || isInstalledGlobally()) {
-    return base;
+    log.debug(
+      `Version source: ${process.env.npm_package_version ? 'npm_package_version' : 'global install'}`,
+    );
+    const version = base;
+    log.debug(`Resolved version: ${version}`);
+    return version;
   }
 
   // Running from source — git tags are the version source of truth.
@@ -27,20 +33,33 @@ function getVersion() {
       const dirty = tagMatch[4];
 
       // Exactly on a clean tag — return the tag version
-      if (!commits && !dirty) return gitVersion;
+      if (!commits && !dirty) {
+        log.debug('Version source: git describe');
+        const version = gitVersion;
+        log.debug(`Resolved version: ${version}`);
+        return version;
+      }
 
       // Build a combined semver-style dev string
       let ver = `${gitVersion}-dev`;
       if (commits) ver += `.${commits}`;
       const meta = [hash ? `g${hash}` : null, dirty ? 'dirty' : null].filter(Boolean).join('.');
       if (meta) ver += `+${meta}`;
+      log.debug('Version source: git describe');
+      log.debug(`Resolved version: ${ver}`);
       return ver;
     }
 
     // No semver tag found (e.g. bare commit hash) — fall back to package.json
-    return `${base}-dev+${gitDesc}`;
+    log.debug('Version source: package.json fallback');
+    const version = `${base}-dev+${gitDesc}`;
+    log.debug(`Resolved version: ${version}`);
+    return version;
   } catch {
-    return `${base}-dev`;
+    log.debug('Version source: package.json fallback');
+    const version = `${base}-dev`;
+    log.debug(`Resolved version: ${version}`);
+    return version;
   }
 }