@ts47andres/exeggutor 1.1.2

package/packages/backend/src/ptyManager.ts

@@ -0,0 +1,414 @@
+import * as pty from 'node-pty';
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+import { exec } from 'child_process';
+import * as db from './workspaceDb'; // Reference to local sessions JSON database.
+
+export interface TerminalSession {
+  id: string; // The unique tab ID associated with this terminal process.
+  workspaceId: string; // The ID of the workspace that owns this session.
+  ptyProcess: pty.IPty; // The live node-pty process instance.
+  outputBuffer: string[]; // Accumulated recent terminal output lines.
+  lastOutputTime: number; // Unix timestamp of the last stdout chunk received.
+  status: 'Active' | 'Waiting' | 'Idle' | 'Errored'; // Real-time state of the terminal process.
+  lastLinePreview: string; // The single most recent line of terminal output for sidebar observers.
+  onData: (data: string) => void; // Event dispatcher callback for new stdout streams.
+  activeSocket?: any; // The active WebSocket connection associated with this session.
+  broadcastCallback?: () => void; // Optional callback to notify observer of state changes.
+}
+
+const sessions = new Map<string, TerminalSession>(); // Global map cache linking tab IDs to their active persistent TerminalSessions.
+let statusCheckInterval: NodeJS.Timeout | null = null; // Background interval reference for running periodic status audits.
+let spawnLock: Promise<void> | null = null; // Mutex promise ensuring only one PTY spawn executes at a time on Windows.
+let killLock: Promise<void> | null = null; // Mutex promise ensuring only one PTY kill executes at a time on Windows.
+
+// Queries the operating system to recursively find all active child and descendant process IDs of the specified parent process.
+function getDescendants(parentPid: number): Promise<Array<{ pid: number; name: string }>> {
+  console.log(`[PTY] getDescendants(parentPid=${parentPid})`);
+  const p = new Promise<Array<{ pid: number; name: string }>>((resolve) => {
+    const isWin = process.platform === 'win32'; // Flag denoting if the host operating system is Windows.
+    const cmd = isWin ? 'wmic process get ParentProcessId,ProcessId,Name' : 'ps -A -o ppid,pid,comm'; // System command to run.
+    console.log(`[PTY] getDescendants -> running: "${cmd}"`);
+    const runOptions = { windowsHide: true }; // Hide window option.
+    exec(cmd, runOptions, (err, stdout) => {
+      if (err || !stdout) {
+        resolve([]);
+        return;
+      }
+      const lines = stdout.split(/\r?\n/); // Process lines array.
+      const procList: Array<{ pid: number; ppid: number; name: string }> = []; // Registry of all active system processes.
+      for (const line of lines) {
+        const parts = line.trim().split(/\s+/); // Splitted columns.
+        if (parts.length >= 3) {
+          if (isWin) {
+            const ppid = parseInt(parts[0], 10); // Parent process identifier.
+            const pid = parseInt(parts[1], 10); // Target process identifier.
+            const name = parts.slice(2).join(' '); // Process executable name.
+            if (!isNaN(pid) && !isNaN(ppid)) {
+              procList.push({ pid, ppid, name });
+            }
+          } else {
+            const ppid = parseInt(parts[0], 10); // Parent process identifier.
+            const pid = parseInt(parts[1], 10); // Target process identifier.
+            const name = parts.slice(2).join(' '); // Executable name or command line.
+            if (!isNaN(pid) && !isNaN(ppid)) {
+              procList.push({ pid, ppid, name });
+            }
+          }
+        }
+      }
+
+      const descendants: Array<{ pid: number; name: string }> = []; // Flat registry of descendant processes.
+      const queue = [parentPid]; // Queue container for breath-first traversal.
+      const visited = new Set<number>(); // Visited PID tracker to prevent circular reference locks.
+      while (queue.length > 0) {
+        const current = queue.shift()!; // Dequeued parent PID.
+        if (visited.has(current)) {
+          continue;
+        }
+        visited.add(current);
+        const children = procList.filter(p => p.ppid === current); // Direct children matching current process.
+        for (const child of children) {
+          descendants.push({ pid: child.pid, name: child.name });
+          queue.push(child.pid);
+        }
+      }
+      console.log(`[PTY] getDescendants(${parentPid}) -> ${descendants.length} descendants: [${descendants.map(d => `${d.name}(${d.pid})`).join(', ')}]`);
+      resolve(descendants);
+    });
+  }); // Spawns execution promise handle.
+  return p;
+}
+
+// Audits the activity state of all terminal sessions to update active vs idle/waiting states.
+export function startStatusAuditor(broadcastCallback: () => void): void {
+  if (statusCheckInterval) {
+    return;
+  }
+  statusCheckInterval = setInterval(async () => {
+    const now = Date.now(); // The current high resolution timestamp.
+    let changed = false; // Flag to indicate if any session state changed during this audit cycle.
+    
+    const sessionPromises = Array.from(sessions.values()).map(async (session) => {
+      const descendants = await getDescendants(session.ptyProcess.pid); // Retrieved process descendants of the PTY.
+      const utilityNames = new Set([
+        'winpty-agent.exe', 'conhost.exe', 'powershell.exe', 'cmd.exe',
+        'wmic.exe', 'openconsole.exe', 'conconsole.exe', 'bash', 'zsh', 'sh', 'ps'
+      ]); // Process utility names set.
+      
+      const hasActiveProcess = descendants.some(d => {
+        const nameLower = d.name.toLowerCase(); // Lowercased process name.
+        const isUtility = Array.from(utilityNames).some(u => nameLower.includes(u.toLowerCase())); // Flag identifying utility processes.
+        return !isUtility;
+      }); // Verification flag identifying if any non-utility process is running.
+
+      if (!hasActiveProcess) {
+        if (session.status !== 'Idle') {
+          session.status = 'Idle';
+          changed = true;
+        }
+      } else {
+        if (session.status === 'Active' && now - session.lastOutputTime > 2000) {
+          const fullOutput = session.outputBuffer.join(''); // Combined stdout stream of the session.
+          const lines = fullOutput.split(/\r?\n/); // Splitted chunk array.
+          const nonLines = lines.map(l => l.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '').trim()); // Cleaned line array without ANSI.
+          const nonZeroLines = nonLines.filter(l => l.length > 0); // Non-empty cleaned lines.
+          const lastFewLines = nonZeroLines.slice(-5); // Last 5 non-empty output lines.
+          const lastFewTextLower = lastFewLines.join(' ').toLowerCase(); // Combined lowercased string of recent lines.
+          const interactiveGuides = ['tab', 'select', 'enter', 'confirm', 'dismiss', 'arrow', 'esc', 'up/down', '[y/n]']; // Interactive keyboard control terms.
+          const promptIndicators = ['password:', 'password for', 'enter passphrase', 'input:', 'confirm:', 'proceed?']; // Standard CLI input indicators.
+          const hasInteractiveGuides = interactiveGuides.some(guide => lastFewTextLower.includes(guide)); // Flag identifying key guides in output.
+          const hasPromptIndicators = promptIndicators.some(indicator => lastFewTextLower.includes(indicator)); // Flag identifying standard prompts in output.
+          const lastLine = nonZeroLines[nonZeroLines.length - 1] || ''; // The single last line of output.
+          const endsWithQuestion = lastLine.endsWith('?') || lastFewLines.some(l => l.endsWith('?')); // Flag verifying if any recent lines end with a question mark.
+          const isWaiting = hasInteractiveGuides || hasPromptIndicators || endsWithQuestion; // Combined check for form prompt or question.
+          const nextStatus = isWaiting ? 'Waiting' : 'Idle'; // Computed target status mapping.
+          session.status = nextStatus;
+          changed = true;
+        }
+      }
+    }); // Spawns concurrent auditing sessions.
+
+    await Promise.all(sessionPromises);
+    if (changed) {
+      broadcastCallback();
+    }
+  }, 5000); // Trigger auditor check every 5 seconds to reduce wmic process spawn frequency on Windows.
+}
+
+// Spawns a persistent terminal process or retrieves an existing one, matching it to the tab.
+// Uses an async spawn lock to serialize concurrent node-pty process creation on Windows.
+export async function getOrCreatePtySession(
+  workspaceId: string,
+  tabId: string,
+  cwd: string,
+  shellPath?: string,
+  broadcastCallback?: () => void
+): Promise<TerminalSession> {
+  const existing = sessions.get(tabId); // Attempt to retrieve an existing session from the cache.
+  if (existing) {
+    console.log(`[PTY] getOrCreatePtySession -> returning existing session for tab=${tabId} PID=${existing.ptyProcess.pid}`);
+    const foundSession = existing; // Explicit reference to the cached session.
+    return foundSession;
+  }
+
+  console.log(`[PTY] getOrCreatePtySession(workspaceId=${workspaceId}, tabId=${tabId}, cwd=${cwd}, shellPath=${shellPath})`);
+
+  const defaultShell = os.platform() === 'win32' ? 'powershell.exe' : 'bash'; // Choose shell path depending on underlying server OS.
+  const targetShell = shellPath || defaultShell; // Evaluated shell executable to run.
+
+  const ptyArgs: string[] = []; // Arguments passed to the spawned shell.
+  const ptyEnv = { ...process.env } as Record<string, string>; // Environment variables for the spawned process.
+
+  const isWin = os.platform() === 'win32'; // Flag indicating Windows platform.
+  if (isWin) {
+    const guardScript = path.resolve(__dirname, '../scripts/git-guard.ps1');
+    if (fs.existsSync(guardScript)) {
+      ptyArgs.push('-NoLogo', '-NoExit', '-ExecutionPolicy', 'Bypass', '-Command', `. '${guardScript}'`);
+    }
+  } else {
+    const wrapperDir = path.resolve(__dirname, '../git-wrapper');
+    if (fs.existsSync(path.join(wrapperDir, 'git'))) {
+      ptyEnv.PATH = `${wrapperDir}${path.delimiter}${ptyEnv.PATH || ''}`;
+    }
+  }
+
+  // Wait for any in-flight PTY spawn to finish before creating a new one to avoid ConPTY conflicts on Windows.
+  while (spawnLock) {
+    console.log(`[PTY] Spawn lock held, waiting for tab=${tabId}`);
+    await spawnLock;
+  }
+  let releaseLock: () => void = () => {}; // Callback to release the spawn mutex after creation completes, default no-op to avoid TS usage-before-init.
+  spawnLock = new Promise((resolve) => { releaseLock = resolve; });
+
+  console.log(`[PTY] Spawning shell: targetShell="${targetShell}" args=[${ptyArgs.join(', ')}] useConpty=true`);
+  let ptyProcess: pty.IPty; // Reference to the successfully spawned node-pty process.
+  try {
+    ptyProcess = pty.spawn(targetShell, ptyArgs, {
+      name: 'xterm-256color',
+      cols: 80,
+      rows: 24,
+      cwd: cwd,
+      env: ptyEnv,
+      useConpty: true, // Enables the Windows Pseudo Console API for accurate dimension resizes.
+    }); // Spawn the process via node-pty.
+    console.log(`[PTY] Spawned PID=${ptyProcess.pid} for tab=${tabId}`);
+  } catch (err: any) {
+    console.log(`[PTY] Spawn FAILED for tab=${tabId}: ${err.message}. Stack: ${err.stack}`);
+    const spawnErr = new Error(`PTY spawn failed for tab ${tabId}: ${err.message}`); // Error wrapping the spawn failure.
+    spawnLock = null;
+    releaseLock();
+    throw spawnErr;
+  }
+  spawnLock = null;
+  releaseLock();
+
+  const newSession: TerminalSession = {
+    id: tabId,
+    workspaceId: workspaceId,
+    ptyProcess: ptyProcess,
+    outputBuffer: [],
+    lastOutputTime: Date.now(),
+    status: 'Idle',
+    lastLinePreview: '',
+    onData: () => {},
+    broadcastCallback: broadcastCallback,
+  }; // The new terminal session schema instance mapping this tab.
+
+  sessions.set(tabId, newSession);
+
+  // Save process PID to database for future orphan recovery.
+  try {
+    db.updateTerminalTab(workspaceId, tabId, { pid: ptyProcess.pid });
+  } catch (err) {
+    // Safe ignore database update failure.
+  }
+
+  ptyProcess.onData(data => {
+    newSession.lastOutputTime = Date.now();
+    
+    const maxBufferLines = 1000; // Limit total cached rows in memory to save memory usage.
+    newSession.outputBuffer.push(data);
+    if (newSession.outputBuffer.length > maxBufferLines) {
+      newSession.outputBuffer.shift();
+    }
+
+    const lines = data.split(/\r?\n/); // Splitted chunk array.
+    const lastNonEmpty = lines.filter(l => l.trim().length > 0).pop(); // The last non-empty line of text.
+    if (lastNonEmpty) {
+      const cleanLine = lastNonEmpty.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '').trim(); // Remove ANSI terminal escape codes.
+      if (cleanLine.length > 0) {
+        newSession.lastLinePreview = cleanLine.substring(0, 100);
+      }
+    }
+
+    const oldStatus = newSession.status; // Preserve original status before computation.
+    newSession.status = 'Active'; // Mark status as active immediately when receiving new data.
+
+    newSession.onData(data);
+
+    if (oldStatus !== newSession.status && broadcastCallback) {
+      broadcastCallback();
+    }
+  });
+
+  ptyProcess.onExit(res => {
+    newSession.status = res.exitCode === 0 ? 'Idle' : 'Errored';
+    if (broadcastCallback) {
+      broadcastCallback();
+    }
+  });
+
+  const createdSession = newSession; // Explicit reference to return.
+  return createdSession;
+}
+
+// Resizes the terminal process row and column dimensions.
+export function resizePtySession(tabId: string, cols: number, rows: number): void {
+  const session = sessions.get(tabId); // Look up session by ID.
+  if (session && typeof cols === 'number' && typeof rows === 'number' && cols > 0 && rows > 0) {
+    const parsedCols = Math.max(Math.floor(cols), 40); // Ensures PTY size is at least 40 columns wide.
+    const parsedRows = Math.max(Math.floor(rows), 10); // Ensures PTY size is at least 10 rows high.
+    if (parsedCols > 0 && parsedRows > 0) {
+      session.ptyProcess.resize(parsedCols, parsedRows);
+    }
+  }
+}
+
+// Write input data directly to the active terminal process.
+// Does not change the session status — the periodic auditor handles status transitions,
+// preventing rapid Idle↔Active flickering that occurred on every keystroke.
+export function writeToPtySession(tabId: string, data: string): void {
+  const session = sessions.get(tabId); // Look up session by ID.
+  if (session) {
+    session.ptyProcess.write(data);
+  }
+}
+
+// Forces the termination of a terminal session and frees system process resources.
+// Serializes concurrent kills on Windows to avoid overlapping conhost termination window flashes.
+export async function killPtySession(tabId: string): Promise<void> {
+  const session = sessions.get(tabId); // Find session by tab ID.
+  if (session) {
+    console.log(`[PTY] killPtySession(tabId=${tabId}) -> killing PID=${session.ptyProcess.pid}`);
+    // Wait for any in-flight PTY kill to finish before terminating this one to avoid ConPTY conflicts on Windows.
+    while (killLock) {
+      console.log(`[PTY] Kill lock held, waiting for tab=${tabId}`);
+      await killLock;
+    }
+    let releaseKillLock: () => void = () => {}; // Callback to release the kill mutex after termination completes.
+    killLock = new Promise((resolve) => { releaseKillLock = resolve; });
+
+    try {
+      session.ptyProcess.kill();
+      console.log(`[PTY] killPtySession(tabId=${tabId}) -> kill OK`);
+    } catch (err: any) {
+      console.log(`[PTY] killPtySession(tabId=${tabId}) -> kill error: ${err.message}`);
+    } finally {
+      killLock = null;
+      releaseKillLock();
+    }
+    try {
+      db.updateTerminalTab(session.workspaceId, tabId, { pid: undefined }); // Clear the PID record from the database.
+    } catch (err) {
+      // Safe ignore database write failure.
+    }
+    sessions.delete(tabId);
+    console.log(`[PTY] killPtySession(tabId=${tabId}) -> session removed from map`);
+  } else {
+    console.log(`[PTY] killPtySession(tabId=${tabId}) -> no active session found`);
+  }
+}
+
+// Retrieves all terminal session descriptors currently managed by the backend.
+export function getAllSessions(): Array<{ id: string; workspaceId: string; status: string; preview: string }> {
+  const list: Array<{ id: string; workspaceId: string; status: string; preview: string }> = []; // Return sessions descriptors.
+  sessions.forEach(s => {
+    list.push({
+      id: s.id,
+      workspaceId: s.workspaceId,
+      status: s.status,
+      preview: s.lastLinePreview,
+    });
+  });
+  return list;
+}
+
+// Verifies that a given PID belongs to an expected Exeggutor-managed process to avoid killing unrelated recycled PIDs.
+function verifyPidOwnership(pid: number): Promise<boolean> {
+  console.log(`[PTY] verifyPidOwnership(pid=${pid})`);
+  return new Promise((resolve) => {
+    const isWin = process.platform === 'win32'; // Flag indicating Windows platform.
+    if (isWin) {
+      console.log(`[PTY] verifyPidOwnership -> running: tasklist /FI "PID eq ${pid}"`);
+      exec(`tasklist /FI "PID eq ${pid}" /FO CSV /NH`, { windowsHide: true }, (err, stdout) => {
+        if (err || !stdout) {
+          resolve(false);
+          return;
+        }
+        const nameMatch = stdout.match(/"([^"]+)"/); // Capture the process executable name from CSV output.
+        if (!nameMatch) {
+          resolve(false);
+          return;
+        }
+        const name = nameMatch[1].toLowerCase(); // Process name from tasklist.
+        const knownNames = ['node.exe', 'powershell.exe', 'cmd.exe', 'bash.exe', 'wmic.exe', 'conhost.exe'];
+        const result = knownNames.some(k => name.includes(k));
+        console.log(`[PTY] verifyPidOwnership(${pid}) -> process="${name}" known=${result}`);
+        resolve(result);
+      }); // Spawn tasklist to verify process identity.
+    } else {
+      try {
+        const comm = fs.readFileSync(`/proc/${pid}/comm`, 'utf8').trim(); // Process command name from proc filesystem.
+        const knownNames = ['node', 'bash', 'zsh', 'sh', 'dash', 'powershell'];
+        const result = knownNames.includes(comm);
+        console.log(`[PTY] verifyPidOwnership(${pid}) -> process="${comm}" known=${result}`);
+        resolve(result);
+      } catch {
+        console.log(`[PTY] verifyPidOwnership(${pid}) -> error reading /proc/${pid}/comm`);
+        resolve(false);
+      }
+    }
+  }); // Verifies that the PID matches an expected Exeggutor-managed process.
+}
+
+// Scans the database for previously persisted terminal tab process IDs and forcefully terminates any orphaned instances.
+export async function cleanOrphanedPtyProcesses(): Promise<void> {
+  try {
+    const workspaces = db.getWorkspaces(); // Load workspaces from database.
+    console.log(`[PTY] cleanOrphanedPtyProcesses() -> scanning ${workspaces.length} workspaces`);
+    for (const ws of workspaces) {
+      console.log(`[PTY] cleanOrphanedPtyProcesses -> workspace=${ws.id} (${ws.name}) has ${ws.tabs.length} tabs`);
+      for (const tab of ws.tabs) {
+        if (tab.pid) {
+          console.log(`[PTY] cleanOrphanedPtyProcesses -> checking tab=${tab.id} PID=${tab.pid}`);
+          const ownsPid = await verifyPidOwnership(tab.pid); // Flag confirming the PID belongs to an expected process.
+          if (!ownsPid) {
+            console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} not owned, clearing record`);
+            try {
+              db.updateTerminalTab(ws.id, tab.id, { pid: undefined }); // Clear stale PID record without killing.
+            } catch (err) {
+              // Safe ignore database write failure.
+            }
+            continue;
+          }
+          console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} owned, sending SIGKILL`);
+          try {
+            process.kill(tab.pid, 'SIGKILL'); // Force terminate the orphaned shell process.
+            console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} killed`);
+          } catch (err: any) {
+            console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} kill error: ${err.message}`);
+          }
+          try {
+            db.updateTerminalTab(ws.id, tab.id, { pid: undefined }); // Clear the PID record from the database.
+          } catch (err) {
+            // Safe ignore database write failure.
+          }
+        }
+      }
+    }
+  } catch (err: any) {
+    console.log(`[PTY] cleanOrphanedPtyProcesses() -> error: ${err.message}`);
+  }
+}

package/packages/backend/src/tailscale.ts

@@ -0,0 +1,138 @@
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// Describes the parsed result of `tailscale status --json` for the local node.
+export interface TailscaleInfo {
+  ip: string; // Tailscale IPv4 address of the local machine.
+  dnsName: string; // MagicDNS hostname (e.g. "hostname.tailnet.ts.net").
+  online: boolean; // Whether this node is currently connected to the tailnet.
+  tailnetName: string; // Human-readable tailnet name from status.
+}
+
+// Resolved path to the tailscale binary, or null if not found.
+let _tailscalePath: string | null | undefined = undefined;
+
+// Common installation paths for the tailscale CLI across platforms.
+function getCommonTailscalePaths(): string[] {
+  const platform = os.platform(); // Operating system identifier.
+  const paths: string[] = [];
+  if (platform === 'win32') {
+    paths.push('C:\\Program Files\\Tailscale\\tailscale.exe');
+    const programFilesX86 = process.env['ProgramFiles(x86)'];
+    if (programFilesX86) {
+      paths.push(path.join(programFilesX86, 'Tailscale', 'tailscale.exe'));
+    }
+  } else if (platform === 'darwin') {
+    paths.push('/Applications/Tailscale.app/Contents/MacOS/Tailscale');
+    paths.push('/usr/local/bin/tailscale');
+  } else {
+    paths.push('/usr/bin/tailscale');
+    paths.push('/usr/local/bin/tailscale');
+    paths.push('/opt/tailscale/tailscale');
+  }
+  return paths;
+}
+
+// Locates the tailscale binary by checking common install paths in addition to PATH.
+function findTailscaleBinary(): string | null {
+  if (_tailscalePath !== undefined) {
+    return _tailscalePath;
+  }
+  try {
+    execSync('tailscale version', { stdio: 'ignore', timeout: 3000 });
+    _tailscalePath = 'tailscale';
+    return _tailscalePath;
+  } catch {
+    // Not in PATH, check common install locations.
+  }
+  for (const candidate of getCommonTailscalePaths()) {
+    if (existsSync(candidate)) {
+      _tailscalePath = candidate;
+      return _tailscalePath;
+    }
+  }
+  _tailscalePath = null;
+  return null;
+}
+
+// Returns true if the `tailscale` CLI binary is found on the system.
+export function isTailscaleInstalled(): boolean {
+  return findTailscaleBinary() !== null;
+}
+
+// Resolves the tailscale CLI binary path for executing commands.
+function tailscaleBin(): string {
+  const bin = findTailscaleBinary(); // Located tailscale binary path.
+  if (!bin) {
+    throw new Error('Tailscale CLI not found');
+  }
+  return bin;
+}
+
+// Parses the local node state from `tailscale status --json`.
+// Returns null if Tailscale is not running or the binary is unavailable.
+export function getTailscaleInfo(): TailscaleInfo | null {
+  if (!isTailscaleInstalled()) {
+    return null;
+  }
+  try {
+    const raw = execSync(`"${tailscaleBin()}" status --json`, {
+      encoding: 'utf8',
+      timeout: 5000,
+    }); // Raw JSON output from the tailscale status command.
+
+    const parsed = JSON.parse(raw); // Parsed status payload from the tailscale daemon.
+
+    const self = parsed.Self; // The local node descriptor from the status object.
+    if (!self) {
+      return null;
+    }
+
+    const ipv4 = (self.TailscaleIPs || []).find((addr: string) =>
+      addr.startsWith('100.')
+    ) as string | undefined; // First 100.x.x.x Tailscale IP assigned to this node.
+
+    const dnsNameRaw = self.DNSName || ''; // Raw DNS name with trailing dot.
+    const dnsName = dnsNameRaw.replace(/\.$/, ''); // Strip the trailing dot.
+
+    const tailnetName = dnsName.split('.').slice(1).join('.') || 'unknown'; // Tailnet identifier extracted from the DNS name.
+
+    return {
+      ip: ipv4 || 'unknown',
+      dnsName: dnsName || 'unknown',
+      online: self.Online !== false,
+      tailnetName,
+    };
+  } catch {
+    return null;
+  }
+}
+
+// Returns the Tailscale IPv4 address of this node, or null if unavailable.
+export function getTailscaleIP(): string | null {
+  const info = getTailscaleInfo(); // Parsed Tailscale status for the local node.
+  return info ? info.ip : null;
+}
+
+// Returns the MagicDNS hostname (e.g. "mybox.tailnet.ts.net") or null.
+export function getMagicDNSName(): string | null {
+  const info = getTailscaleInfo(); // Parsed Tailscale status for the local node.
+  return info ? info.dnsName : null;
+}
+
+// Returns the full URL to access Exeggutor via Tailscale, or null.
+export function getTailscaleURL(port: number): string | null {
+  const dnsName = getMagicDNSName(); // MagicDNS hostname of the local node.
+  if (dnsName) {
+    return `https://${dnsName}:${port}`;
+  }
+  const ip = getTailscaleIP(); // Tailscale IP of the local node.
+  if (ip) {
+    return `http://${ip}:${port}`;
+  }
+  return null;
+}
+
+