termbeam 1.7.0 → 1.8.0

package/README.md

@@ -46,6 +46,8 @@ termbeam
 
 Scan the QR code printed in your terminal, or open the URL on any device.
 
+> **First time?** Run `termbeam -i` for a guided setup wizard that walks you through password, port, and access mode.
+
 ### Secure by default
 
 TermBeam starts with a tunnel and auto-generated password out of the box — just run `termbeam` and scan the QR code.
@@ -55,6 +57,7 @@ termbeam                        # tunnel + auto-password (default)
 termbeam --password mysecret    # use a specific password
 termbeam --no-tunnel            # LAN-only (no tunnel)
 termbeam --no-password          # disable password protection
+termbeam -i                     # interactive setup wizard
 ```
 
 ## Remote Access
@@ -85,6 +88,7 @@ termbeam [shell] [args...]        # start with a specific shell (default: auto-d
 termbeam --port 8080              # custom port (default: 3456)
 termbeam --host 0.0.0.0           # allow LAN access (default: 127.0.0.1)
 termbeam --lan                    # shortcut for --host 0.0.0.0
+termbeam -i                       # interactive setup wizard
 termbeam service install          # interactive PM2 service setup wizard
 termbeam service uninstall        # stop & remove PM2 service
 termbeam service status           # show PM2 service status
@@ -105,6 +109,7 @@ termbeam service restart          # restart PM2 service
 | `--host <addr>`       | Bind address                                         | `127.0.0.1`    |
 | `--lan`               | Bind to all interfaces (LAN access)                  | Off            |
 | `--log-level <level>` | Log verbosity (error/warn/info/debug)                | `info`         |
+| `-i, --interactive`   | Interactive setup wizard (guided configuration)      | Off            |
 | `-h, --help`          | Show help                                            | —              |
 | `-v, --version`       | Show version                                         | —              |
 

package/bin/termbeam.js

@@ -10,18 +10,33 @@ if (subcommand === 'service') {
   });
 } else {
   const { createTermBeamServer } = require('../src/server.js');
-  const instance = createTermBeamServer();
+  const { parseArgs } = require('../src/cli');
+  const { runInteractiveSetup } = require('../src/interactive');
 
-  process.on('SIGINT', () => {
-    console.log('\n[termbeam] Shutting down...');
-    instance.shutdown();
-    setTimeout(() => process.exit(0), 500).unref();
-  });
-  process.on('SIGTERM', () => {
-    console.log('\n[termbeam] Shutting down...');
-    instance.shutdown();
-    setTimeout(() => process.exit(0), 500).unref();
-  });
+  async function main() {
+    const baseConfig = parseArgs();
+    let config;
+    if (baseConfig.interactive) {
+      config = await runInteractiveSetup(baseConfig);
+    }
+    const instance = createTermBeamServer(config ? { config } : undefined);
+
+    process.on('SIGINT', () => {
+      console.log('\n[termbeam] Shutting down...');
+      instance.shutdown();
+      setTimeout(() => process.exit(0), 500).unref();
+    });
+    process.on('SIGTERM', () => {
+      console.log('\n[termbeam] Shutting down...');
+      instance.shutdown();
+      setTimeout(() => process.exit(0), 500).unref();
+    });
+
+    instance.start();
+  }
 
-  instance.start();
+  main().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termbeam",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Beam your terminal to any device — mobile-optimized web terminal with multi-session support",
   "main": "src/server.js",
   "bin": {

package/src/cli.js

@@ -31,6 +31,7 @@ Options:
   --host <addr>         Bind address (default: 127.0.0.1)
   --lan                 Bind to 0.0.0.0 (allow LAN access, default: localhost only)
   --log-level <level>   Set log verbosity: error, warn, info, debug (default: info)
+  -i, --interactive     Interactive setup wizard (guided configuration)
   -h, --help            Show this help
   -v, --version         Show version
 
@@ -47,6 +48,7 @@ Examples:
   termbeam --password secret        Start with specific password
   termbeam --persisted-tunnel       Stable tunnel URL across restarts
   termbeam /bin/bash                Use bash instead of default shell
+  termbeam --interactive               Guided setup wizard
   termbeam service install          Set up as background service (PM2)
 
 Environment:
@@ -241,6 +243,7 @@ function parseArgs() {
   let noTunnel = false;
   let persistedTunnel = false;
   let publicTunnel = false;
+  let interactive = false;
   let explicitPassword = !!password;
 
   const args = process.argv.slice(2);
@@ -281,6 +284,8 @@ function parseArgs() {
       host = '0.0.0.0';
     } else if (args[i] === '--host' && args[i + 1]) {
       host = args[++i];
+    } else if (args[i] === '--interactive' || (args[i] === '-i' && filteredArgs.length === 0)) {
+      interactive = true;
     } else if (args[i] === '--log-level' && args[i + 1]) {
       logLevel = args[++i];
     } else {
@@ -335,6 +340,7 @@ function parseArgs() {
     defaultShell,
     version,
     logLevel,
+    interactive,
   };
 }
 

package/src/interactive.js

@@ -0,0 +1,269 @@
+const crypto = require('crypto');
+const {
+  green,
+  yellow,
+  red,
+  cyan,
+  bold,
+  dim,
+  ask,
+  choose,
+  confirm,
+  createRL,
+} = require('./prompts');
+
+// ── Interactive Setup Wizard ─────────────────────────────────────────────────
+
+async function runInteractiveSetup(baseConfig) {
+  // Enter alternate screen buffer for a clean wizard (like vim/htop)
+  process.stdout.write('\x1b[?1049h');
+  const exitAltScreen = () => process.stdout.write('\x1b[?1049l');
+  process.on('exit', exitAltScreen);
+
+  const rl = createRL();
+
+  const steps = ['Password', 'Port', 'Access', 'Log level', 'Confirm'];
+  const decisions = [];
+
+  function showProgress(stepIndex) {
+    process.stdout.write('\x1b[2J\x1b[H');
+
+    console.log(bold('🚀 TermBeam Interactive Setup'));
+    console.log('');
+    const total = steps.length;
+    const filled = stepIndex + 1;
+    const bar = steps
+      .map((s, i) => {
+        if (i < stepIndex) return green('●');
+        if (i === stepIndex) return cyan('●');
+        return dim('○');
+      })
+      .join(dim(' ─ '));
+    console.log(`${dim(`Step ${filled}/${total}`)}  ${bar}  ${cyan(steps[stepIndex])}`);
+
+    if (decisions.length > 0) {
+      console.log('');
+      for (const { label, value } of decisions) {
+        console.log(`  ${dim(label + ':')} ${value}`);
+      }
+    }
+  }
+
+  // Build config from base
+  const config = {
+    port: baseConfig.port,
+    host: baseConfig.host,
+    password: baseConfig.password,
+    useTunnel: baseConfig.useTunnel,
+    persistedTunnel: baseConfig.persistedTunnel,
+    publicTunnel: baseConfig.publicTunnel,
+    shell: baseConfig.shell,
+    shellArgs: baseConfig.shellArgs,
+    cwd: baseConfig.cwd,
+    defaultShell: baseConfig.defaultShell,
+    version: baseConfig.version,
+    logLevel: baseConfig.logLevel,
+  };
+
+  // Step 1: Password
+  showProgress(0);
+  const pwChoice = await choose(rl, 'Password authentication:', [
+    {
+      label: 'Auto-generate',
+      hint: 'Random password, shown on screen and embedded in the QR code',
+    },
+    {
+      label: 'Custom password',
+      hint: 'You type a password to use for this session',
+    },
+    {
+      label: 'No password',
+      hint: '⚠ No authentication — anyone who can reach the server gets shell access',
+      warn: true,
+    },
+  ]);
+  let passwordMode = 'auto';
+  if (pwChoice.index === 0) {
+    config.password = crypto.randomBytes(16).toString('base64url');
+    console.log(dim(`  Generated password: ${config.password}`));
+  } else if (pwChoice.index === 1) {
+    passwordMode = 'custom';
+    config.password = await ask(rl, 'Enter password:');
+    while (!config.password) {
+      console.log(red('  Password cannot be empty.'));
+      config.password = await ask(rl, 'Enter password:');
+    }
+  } else {
+    passwordMode = 'none';
+    config.password = null;
+  }
+  decisions.push({
+    label: 'Password',
+    value: config.password == null ? yellow('disabled') : '••••••••',
+  });
+
+  // Step 2: Port
+  showProgress(1);
+  const portStr = await ask(rl, 'Port:', String(config.port));
+  const portNum = parseInt(portStr, 10);
+  config.port = portNum >= 1 && portNum <= 65535 ? portNum : 3456;
+  decisions.push({ label: 'Port', value: String(config.port) });
+
+  // Step 3: Access mode
+  showProgress(2);
+  const accessChoice = await choose(rl, 'How will you connect to TermBeam?', [
+    {
+      label: 'DevTunnel (internet)',
+      hint: 'HTTPS tunnel — accessible from any network, secured with your Microsoft account',
+    },
+    {
+      label: 'LAN',
+      hint: 'Binds to 0.0.0.0 — accessible from devices on the same network',
+    },
+    {
+      label: 'Localhost only',
+      hint: 'Binds to 127.0.0.1 — only this machine can connect',
+    },
+  ]);
+
+  if (accessChoice.index === 0) {
+    // DevTunnel mode
+    config.host = '127.0.0.1';
+    config.useTunnel = true;
+
+    // Sub-question: tunnel persistence
+    showProgress(2);
+    const persistChoice = await choose(rl, 'Tunnel persistence:', [
+      {
+        label: 'Ephemeral',
+        hint: 'New URL each run, automatically deleted when TermBeam exits',
+      },
+      {
+        label: 'Persisted',
+        hint: 'Stable URL that survives restarts (expires after 30 days idle)',
+      },
+    ]);
+    config.persistedTunnel = persistChoice.index === 1;
+
+    // Sub-question: access level
+    showProgress(2);
+    const publicChoice = await choose(rl, 'Tunnel access:', [
+      {
+        label: 'Private (owner-only)',
+        hint: 'Only the Microsoft account that created the tunnel can access it',
+      },
+      {
+        label: 'Public',
+        hint: '🚨 No Microsoft login — anyone with the URL can reach your terminal',
+        danger: true,
+      },
+    ]);
+    config.publicTunnel = publicChoice.index === 1;
+
+    // Auto-generate password if public tunnel with no password
+    if (config.publicTunnel && !config.password) {
+      console.log(yellow('  ⚠ Public tunnels require password authentication.'));
+      config.password = crypto.randomBytes(16).toString('base64url');
+      console.log(dim(`  Auto-generated password: ${config.password}`));
+      passwordMode = 'auto';
+      // Update the password decision
+      decisions[0] = { label: 'Password', value: '••••••••' };
+    }
+  } else if (accessChoice.index === 1) {
+    // LAN mode
+    config.host = '0.0.0.0';
+    config.useTunnel = false;
+    config.persistedTunnel = false;
+    config.publicTunnel = false;
+  } else {
+    // Localhost only
+    config.host = '127.0.0.1';
+    config.useTunnel = false;
+    config.persistedTunnel = false;
+    config.publicTunnel = false;
+  }
+
+  const accessLabel = !config.useTunnel
+    ? config.host === '0.0.0.0'
+      ? 'LAN (0.0.0.0)'
+      : 'Localhost only'
+    : config.publicTunnel
+      ? 'DevTunnel (public)'
+      : 'DevTunnel (private)';
+  decisions.push({ label: 'Access', value: accessLabel });
+
+  // Step 4: Log level
+  showProgress(3);
+  const logChoice = await choose(
+    rl,
+    'Log level:',
+    [
+      { label: 'info', hint: 'Logs startup, connections, sessions, and errors (default)' },
+      { label: 'debug', hint: 'Includes all info logs plus WebSocket frames and internal state' },
+      { label: 'warn', hint: 'Only logs warnings and errors' },
+      { label: 'error', hint: 'Only logs critical errors' },
+    ],
+    0,
+  );
+  config.logLevel = logChoice.value;
+  decisions.push({ label: 'Log level', value: config.logLevel });
+
+  // Step 5: Confirmation
+  showProgress(4);
+  console.log(bold('\n── Configuration Summary ──────────────────'));
+  console.log(
+    `  Password:      ${config.password == null ? yellow('disabled') : cyan('••••••••')}`,
+  );
+  console.log(`  Port:          ${cyan(String(config.port))}`);
+  console.log(
+    `  Host:          ${cyan(config.host === '0.0.0.0' ? '0.0.0.0 (LAN)' : config.host)}`,
+  );
+  console.log(`  Tunnel:        ${config.useTunnel ? cyan('enabled') : yellow('disabled')}`);
+  if (config.useTunnel) {
+    console.log(`  Persisted:     ${config.persistedTunnel ? cyan('yes') : dim('no')}`);
+    console.log(`  Public:        ${config.publicTunnel ? yellow('yes') : dim('no')}`);
+  }
+  console.log(`  Shell:         ${cyan(config.shell || 'default')}`);
+  console.log(`  Directory:     ${cyan(config.cwd)}`);
+  console.log(`  Log level:     ${cyan(config.logLevel)}`);
+  console.log(dim('─'.repeat(44)));
+
+  // Build the equivalent CLI command
+  const cmdParts = ['termbeam'];
+  if (passwordMode === 'none') {
+    cmdParts.push('--no-password');
+  } else if (passwordMode === 'custom') {
+    cmdParts.push('--password', '"<your-password>"');
+  }
+  // auto-generate is the default — no flag needed
+  if (config.port !== 3456) cmdParts.push('--port', String(config.port));
+  if (!config.useTunnel) {
+    cmdParts.push('--no-tunnel');
+    if (config.host === '0.0.0.0') cmdParts.push('--lan');
+  } else {
+    if (config.persistedTunnel) cmdParts.push('--persisted-tunnel');
+    if (config.publicTunnel) cmdParts.push('--public');
+  }
+  if (config.logLevel !== 'info') cmdParts.push('--log-level', config.logLevel);
+  const cliCommand = cmdParts.join(' ');
+
+  console.log('');
+  console.log(dim('  To reuse this configuration without the wizard:'));
+  console.log(`  ${cyan(cliCommand)}`);
+
+  const proceed = await confirm(rl, '\nStart TermBeam with this configuration?', true);
+  rl.close();
+
+  // Exit alternate screen — return to normal terminal
+  exitAltScreen();
+  process.removeListener('exit', exitAltScreen);
+
+  if (!proceed) {
+    console.log(dim('Cancelled.'));
+    process.exit(0);
+  }
+
+  return config;
+}
+
+module.exports = { runInteractiveSetup };

package/src/prompts.js

@@ -0,0 +1,146 @@
+const readline = require('readline');
+
+// ── Color helpers ────────────────────────────────────────────────────────────
+
+function color(code, text) {
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+const green = (t) => color('32', t);
+const yellow = (t) => color('33', t);
+const red = (t) => color('31', t);
+const cyan = (t) => color('36', t);
+const bold = (t) => color('1', t);
+const dim = (t) => color('2', t);
+
+// ── Interactive prompts ──────────────────────────────────────────────────────
+
+/**
+ * Prompt the user with a question. Returns the trimmed answer.
+ * If `defaultValue` is provided, it's shown in brackets and used when the user presses Enter.
+ */
+function ask(rl, question, defaultValue) {
+  const suffix = defaultValue != null ? ` ${dim(`[${defaultValue}]`)} ` : ' ';
+  return new Promise((resolve) => {
+    rl.question(`${question}${suffix}`, (answer) => {
+      const trimmed = answer.trim();
+      resolve(trimmed || (defaultValue != null ? String(defaultValue) : ''));
+    });
+  });
+}
+
+/**
+ * Prompt the user with a list of choices using arrow keys.
+ * Each choice can be a string or { label, hint } object.
+ * Up/Down to move, Enter to select. Returns the chosen value.
+ */
+function choose(rl, question, choices, defaultIndex = 0) {
+  // Normalize choices to { label, hint } objects
+  const items = choices.map((c) => (typeof c === 'string' ? { label: c, hint: '' } : c));
+
+  return new Promise((resolve) => {
+    let selected = defaultIndex;
+
+    function lineCount() {
+      return items.reduce((n, item) => n + 1 + (item.hint ? 1 : 0), 0);
+    }
+
+    function render(clear) {
+      if (clear) {
+        process.stdout.write(`\x1b[${lineCount()}A\r\x1b[J`);
+      }
+      items.forEach((item, i) => {
+        const marker = i === selected ? cyan('→') : ' ';
+        const label = i === selected ? bold(item.label) : item.label;
+        process.stdout.write(`  ${marker} ${label}\n`);
+        if (item.hint) {
+          const hintText = item.danger
+            ? red(item.hint)
+            : item.warn
+              ? yellow(item.hint)
+              : dim(item.hint);
+          process.stdout.write(`      ${hintText}\n`);
+        }
+      });
+      process.stdout.write(dim('  ↑/↓ to move, Enter to select'));
+    }
+
+    rl.pause();
+    console.log(`\n${question}`);
+    render(false);
+
+    const wasRaw = process.stdin.isRaw;
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+
+    function onKey(buf) {
+      const key = buf.toString();
+
+      if (key === '\x1b[A' || key === 'k') {
+        selected = (selected - 1 + items.length) % items.length;
+        render(true);
+      } else if (key === '\x1b[B' || key === 'j') {
+        selected = (selected + 1) % items.length;
+        render(true);
+      } else if (key === '\r' || key === '\n') {
+        cleanup();
+        process.stdout.write('\r\x1b[K\n');
+        console.log(dim(`  Selected: ${items[selected].label}`));
+        resolve({ index: selected, value: items[selected].label });
+      } else if (key === '\x03') {
+        cleanup();
+        process.stdout.write('\x1b[?1049l');
+        process.exit(0);
+      }
+    }
+
+    function cleanup() {
+      process.stdin.removeListener('data', onKey);
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(wasRaw || false);
+      }
+      process.stdin.pause();
+      rl.resume();
+    }
+
+    process.stdin.on('data', onKey);
+  });
+}
+
+/**
+ * Ask a yes/no question. Returns boolean.
+ */
+function confirm(rl, question, defaultYes = true) {
+  const hint = defaultYes ? 'Y/n' : 'y/N';
+  return new Promise((resolve) => {
+    rl.question(`${question} ${dim(`[${hint}]`)} `, (answer) => {
+      const a = answer.trim().toLowerCase();
+      if (a === '') resolve(defaultYes);
+      else resolve(a === 'y' || a === 'yes');
+    });
+  });
+}
+
+// ── readline factory ─────────────────────────────────────────────────────────
+
+function createRL() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+module.exports = {
+  color,
+  green,
+  yellow,
+  red,
+  cyan,
+  bold,
+  dim,
+  ask,
+  choose,
+  confirm,
+  createRL,
+};

package/src/service.js

@@ -3,131 +3,24 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
-const readline = require('readline');
+const {
+  color,
+  green,
+  yellow,
+  red,
+  cyan,
+  bold,
+  dim,
+  ask,
+  choose,
+  confirm,
+  createRL,
+} = require('./prompts');
 
 const TERMBEAM_DIR = path.join(os.homedir(), '.termbeam');
 const ECOSYSTEM_FILE = path.join(TERMBEAM_DIR, 'ecosystem.config.js');
 const DEFAULT_SERVICE_NAME = 'termbeam';
 
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-function color(code, text) {
-  return `\x1b[${code}m${text}\x1b[0m`;
-}
-const green = (t) => color('32', t);
-const yellow = (t) => color('33', t);
-const red = (t) => color('31', t);
-const cyan = (t) => color('36', t);
-const bold = (t) => color('1', t);
-const dim = (t) => color('2', t);
-
-/**
- * Prompt the user with a question. Returns the trimmed answer.
- * If `defaultValue` is provided, it's shown in brackets and used when the user presses Enter.
- */
-function ask(rl, question, defaultValue) {
-  const suffix = defaultValue != null ? ` ${dim(`[${defaultValue}]`)} ` : ' ';
-  return new Promise((resolve) => {
-    rl.question(`${question}${suffix}`, (answer) => {
-      const trimmed = answer.trim();
-      resolve(trimmed || (defaultValue != null ? String(defaultValue) : ''));
-    });
-  });
-}
-
-/**
- * Prompt the user with a list of choices using arrow keys.
- * Each choice can be a string or { label, hint } object.
- * Up/Down to move, Enter to select. Returns the chosen value.
- */
-function choose(rl, question, choices, defaultIndex = 0) {
-  // Normalize choices to { label, hint } objects
-  const items = choices.map((c) => (typeof c === 'string' ? { label: c, hint: '' } : c));
-
-  return new Promise((resolve) => {
-    let selected = defaultIndex;
-
-    function lineCount() {
-      return items.reduce((n, item) => n + 1 + (item.hint ? 1 : 0), 0);
-    }
-
-    function render(clear) {
-      if (clear) {
-        process.stdout.write(`\x1b[${lineCount()}A\r\x1b[J`);
-      }
-      items.forEach((item, i) => {
-        const marker = i === selected ? cyan('→') : ' ';
-        const label = i === selected ? bold(item.label) : item.label;
-        process.stdout.write(`  ${marker} ${label}\n`);
-        if (item.hint) {
-          const hintText = item.danger
-            ? red(item.hint)
-            : item.warn
-              ? yellow(item.hint)
-              : dim(item.hint);
-          process.stdout.write(`      ${hintText}\n`);
-        }
-      });
-      process.stdout.write(dim('  ↑/↓ to move, Enter to select'));
-    }
-
-    rl.pause();
-    console.log(`\n${question}`);
-    render(false);
-
-    const wasRaw = process.stdin.isRaw;
-    if (process.stdin.isTTY) {
-      process.stdin.setRawMode(true);
-    }
-    process.stdin.resume();
-
-    function onKey(buf) {
-      const key = buf.toString();
-
-      if (key === '\x1b[A' || key === 'k') {
-        selected = (selected - 1 + items.length) % items.length;
-        render(true);
-      } else if (key === '\x1b[B' || key === 'j') {
-        selected = (selected + 1) % items.length;
-        render(true);
-      } else if (key === '\r' || key === '\n') {
-        cleanup();
-        process.stdout.write('\r\x1b[K\n');
-        console.log(dim(`  Selected: ${items[selected].label}`));
-        resolve({ index: selected, value: items[selected].label });
-      } else if (key === '\x03') {
-        cleanup();
-        process.exit(0);
-      }
-    }
-
-    function cleanup() {
-      process.stdin.removeListener('data', onKey);
-      if (process.stdin.isTTY) {
-        process.stdin.setRawMode(wasRaw || false);
-      }
-      process.stdin.pause();
-      rl.resume();
-    }
-
-    process.stdin.on('data', onKey);
-  });
-}
-
-/**
- * Ask a yes/no question. Returns boolean.
- */
-function confirm(rl, question, defaultYes = true) {
-  const hint = defaultYes ? 'Y/n' : 'y/N';
-  return new Promise((resolve) => {
-    rl.question(`${question} ${dim(`[${hint}]`)} `, (answer) => {
-      const a = answer.trim().toLowerCase();
-      if (a === '') resolve(defaultYes);
-      else resolve(a === 'y' || a === 'yes');
-    });
-  });
-}
-
 // ── PM2 Detection ────────────────────────────────────────────────────────────
 
 function findPm2() {
@@ -651,15 +544,6 @@ function actionRestart() {
   console.log(green('\n✓ TermBeam service restarted.\n'));
 }
 
-// ── readline factory ─────────────────────────────────────────────────────────
-
-function createRL() {
-  return readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-}
-
 // ── Entrypoint ───────────────────────────────────────────────────────────────
 
 function printServiceHelp() {