teleportation-cli 1.1.5 → 1.2.0

package/.claude/hooks/heartbeat.mjs

@@ -1,396 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Heartbeat Background Process
- * Runs continuously while Claude Code session is active
- * Sends periodic heartbeats to relay API to keep session alive
- *
- * This is NOT a hook - it's a background process spawned by session_start.mjs
- * It runs detached and continues until killed by session_end.mjs
- */
-
-import { env, exit, pid as processPid } from 'node:process';
-import { writeFile, unlink } from 'fs/promises';
-import { tmpdir, homedir } from 'os';
-import { join, dirname } from 'path';
-import { fileURLToPath, pathToFileURL } from 'url';
-
-// Read configuration from environment variables (secure - not visible in process list)
-const SESSION_ID = process.argv[2] || env.SESSION_ID;
-const RELAY_API_URL = env.RELAY_API_URL;
-const RELAY_API_KEY = env.RELAY_API_KEY;
-const HEARTBEAT_INTERVAL = Math.max(100, Math.min(600000,
-  parseInt(env.HEARTBEAT_INTERVAL || '120000', 10)
-)); // Default 2 minutes, min 100ms (for testing), max 10min
-const START_DELAY = Math.max(100, Math.min(60000,
-  parseInt(env.START_DELAY || '5000', 10)
-)); // Default 5 seconds, min 100ms (for testing), max 1min
-const MAX_FAILURES = Math.max(1, Math.min(10,
-  parseInt(env.MAX_FAILURES || '3', 10)
-)); // Default 3, min 1, max 10
-const FETCH_TIMEOUT = Math.max(100, Math.min(30000,
-  parseInt(env.FETCH_TIMEOUT || '5000', 10)
-)); // Default 5s, min 100ms (for testing), max 30s
-const DEBUG = env.TELEPORTATION_DEBUG === 'true';
-
-// Get __dirname equivalent for ES modules
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-if (!SESSION_ID || !RELAY_API_URL || !RELAY_API_KEY) {
-  console.error('[Heartbeat] Missing required environment variables: SESSION_ID, RELAY_API_URL, RELAY_API_KEY');
-  exit(1);
-}
-
-const PID_FILE = join(tmpdir(), `teleportation-heartbeat-${SESSION_ID}.pid`);
-let intervalHandle = null;
-let heartbeatCount = 0;
-let failureCount = 0;
-let lastDaemonCheck = 0;
-// Module cache for lifecycle and pid-manager (imported once, reused)
-let lifecycleModule = null;
-let pidManagerModule = null;
-// Flag to prevent concurrent daemon start attempts
-let daemonStartInProgress = false;
-// Make interval configurable via environment variable (default 60 seconds)
-const DAEMON_CHECK_INTERVAL = Math.max(10000, Math.min(300000,
-  parseInt(env.DAEMON_CHECK_INTERVAL || '60000', 10)
-)); // Default 60 seconds, min 10s, max 5min
-
-/**
- * Update daemon state on relay
- * @param {'running' | 'stopped'} status - Daemon status
- * @param {string} reason - Reason for state change
- */
-async function updateRelayDaemonState(status, reason) {
-  try {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
-
-    const response = await fetch(`${RELAY_API_URL}/api/sessions/${SESSION_ID}/daemon-state`, {
-      method: 'PATCH',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${RELAY_API_KEY}`
-      },
-      body: JSON.stringify({
-        status,
-        started_at: status === 'running' ? Date.now() : null,
-        started_reason: status === 'running' ? reason : null
-      }),
-      signal: controller.signal
-    });
-
-    clearTimeout(timeoutId);
-
-    if (!response.ok && DEBUG) {
-      console.log(`[Heartbeat] Failed to update relay daemon state: ${response.status}`);
-    }
-  } catch (error) {
-    if (DEBUG) {
-      console.log(`[Heartbeat] Error updating relay daemon state: ${error.message}`);
-    }
-    throw error;
-  }
-}
-
-/**
- * Check if daemon is running and start it if not
- */
-async function ensureDaemonRunning() {
-  // Early return with throttle check BEFORE any async operations
-  // This prevents multiple concurrent executions of the expensive module import logic
-  const now = Date.now();
-  if (now - lastDaemonCheck < DAEMON_CHECK_INTERVAL) {
-    return;
-  }
-  // Set timestamp immediately after check to prevent race conditions
-  lastDaemonCheck = now;
-
-  try {
-    // Try to import lifecycle module from installed location
-    const possibleLocations = [
-      // npm global install location
-      '/usr/local/lib/node_modules/teleportation-cli/lib/daemon/lifecycle.js',
-      // User's npm global install (common on macOS with nvm/fnm)
-      join(homedir(), '.local', 'lib', 'node_modules', 'teleportation-cli', 'lib', 'daemon', 'lifecycle.js'),
-      // Legacy location
-      join(homedir(), '.teleportation', 'lib', 'daemon', 'lifecycle.js'),
-      // Relative to hooks dir (development)
-      join(__dirname, '..', '..', 'lib', 'daemon', 'lifecycle.js'),
-      // Environment override
-      env.TELEPORTATION_LIFECYCLE_PATH
-    ].filter(Boolean);
-
-    const { access } = await import('fs/promises');
-    let lifecyclePath = null;
-    for (const location of possibleLocations) {
-      try {
-        await access(location);
-        lifecyclePath = location;
-        break;
-      } catch {
-        // Try next location
-      }
-    }
-
-    if (!lifecyclePath) {
-      if (DEBUG) {
-        console.log('[Heartbeat] Lifecycle module not found, skipping daemon check');
-      }
-      return;
-    }
-
-    // Cache module imports to avoid re-importing on every check
-    // Use pathToFileURL for proper Windows path handling
-    const pidManagerPath = join(dirname(lifecyclePath), 'pid-manager.js');
-    
-    if (!lifecycleModule || !pidManagerModule) {
-      // Only import once, then cache
-      // Use pathToFileURL for cross-platform compatibility (especially Windows)
-      lifecycleModule = await import(pathToFileURL(lifecyclePath).href);
-      pidManagerModule = await import(pathToFileURL(pidManagerPath).href);
-    }
-
-    const lifecycle = lifecycleModule;
-    const { checkDaemonStatus } = pidManagerModule;
-
-    // Check daemon status
-    const status = await checkDaemonStatus();
-    if (!status.running && !daemonStartInProgress) {
-      // Set flag to prevent concurrent start attempts
-      daemonStartInProgress = true;
-      
-      if (DEBUG) {
-        console.log(`[Heartbeat] Daemon not running, attempting to start...`);
-      }
-
-      try {
-        // Use startDaemonIfNeeded to both start the daemon AND update the relay
-        // This ensures the mobile UI knows the daemon is running
-        await lifecycle.startDaemonIfNeeded(SESSION_ID, 'heartbeat');
-        if (DEBUG) {
-          console.log(`[Heartbeat] Daemon started and relay updated successfully`);
-        }
-      } catch (error) {
-        // Don't fail heartbeat if daemon start fails - it might already be starting
-        if (DEBUG) {
-          console.log(`[Heartbeat] Daemon start attempt: ${error.message}`);
-        }
-      } finally {
-        // Always reset flag, even if start fails
-        daemonStartInProgress = false;
-      }
-    } else if (status.running) {
-      // Daemon is running - ensure relay knows about it
-      // This handles the case where daemon was started manually or by another session
-      try {
-        await updateRelayDaemonState('running', 'heartbeat');
-        if (DEBUG) {
-          console.log(`[Heartbeat] Synced daemon running state to relay`);
-        }
-      } catch (error) {
-        // Ignore errors - just a sync, not critical
-        if (DEBUG) {
-          console.log(`[Heartbeat] Failed to sync daemon state: ${error.message}`);
-        }
-      }
-    }
-  } catch (error) {
-    // Silently fail - daemon check shouldn't break heartbeat
-    if (DEBUG) {
-      console.log(`[Heartbeat] Error checking daemon: ${error.message}`);
-    }
-  }
-}
-
-/**
- * Check for pending approvals and handle them
- */
-async function checkAndHandlePendingApprovals() {
-  try {
-    // Fetch pending and allowed approvals for this session
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
-
-    const [pendingResponse, allowedResponse] = await Promise.all([
-      fetch(`${RELAY_API_URL}/api/approvals?status=pending&session_id=${SESSION_ID}`, {
-        headers: {
-          'Authorization': `Bearer ${RELAY_API_KEY}`
-        },
-        signal: controller.signal
-      }),
-      fetch(`${RELAY_API_URL}/api/approvals?status=allowed&session_id=${SESSION_ID}`, {
-        headers: {
-          'Authorization': `Bearer ${RELAY_API_KEY}`
-        },
-        signal: controller.signal
-      })
-    ]);
-
-    clearTimeout(timeoutId);
-
-    if (!pendingResponse.ok && !allowedResponse.ok) {
-      return; // Skip if API calls fail
-    }
-
-    const pending = pendingResponse.ok ? await pendingResponse.json() : [];
-    const allowed = allowedResponse.ok ? await allowedResponse.json() : [];
-
-    // Find allowed approvals that haven't been acknowledged yet
-    const unacknowledged = allowed.filter(a => !a.acknowledgedAt);
-
-    if (unacknowledged.length > 0 && DEBUG) {
-      console.log(`[Heartbeat] Found ${unacknowledged.length} approved but unacknowledged approval(s)`);
-    }
-
-    // Acknowledge approved approvals (fire-and-forget, don't block heartbeat)
-    for (const approval of unacknowledged) {
-      try {
-        fetch(`${RELAY_API_URL}/api/approvals/${approval.id}/ack`, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'Authorization': `Bearer ${RELAY_API_KEY}`
-          },
-          body: JSON.stringify({ processed: true })
-        }).catch(() => {}); // Ignore errors - acknowledgment is optional
-      } catch (e) {
-        // Ignore errors
-      }
-    }
-
-    // Log if there are pending approvals waiting for user decision
-    if (pending.length > 0 && DEBUG) {
-      console.log(`[Heartbeat] Session has ${pending.length} pending approval(s) waiting for user decision`);
-    }
-  } catch (error) {
-    // Silently fail - approval checking shouldn't break heartbeat
-    if (DEBUG) {
-      console.log(`[Heartbeat] Error checking approvals: ${error.message}`);
-    }
-  }
-}
-
-/**
- * Send heartbeat to relay API
- */
-async function sendHeartbeat() {
-  // Increment count before sending (so first heartbeat is #1, not #0)
-  heartbeatCount++;
-
-  try {
-    // Add timeout to prevent hanging on unreachable servers
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
-
-    const response = await fetch(`${RELAY_API_URL}/api/sessions/${SESSION_ID}/heartbeat`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${RELAY_API_KEY}`
-      },
-      body: JSON.stringify({
-        timestamp: new Date().toISOString(),
-        pid: processPid,
-        count: heartbeatCount
-      }),
-      signal: controller.signal
-    });
-
-    clearTimeout(timeoutId); // Clear timeout if request succeeds
-
-    if (response.ok) {
-      failureCount = 0; // Reset failure count on success
-      
-      // Check daemon status and start if needed (asynchronously, don't block heartbeat)
-      ensureDaemonRunning().catch(() => {});
-      
-      // Check for pending approvals after successful heartbeat
-      // Do this asynchronously so it doesn't block the heartbeat
-      checkAndHandlePendingApprovals().catch(() => {});
-      
-      if (DEBUG) {
-        console.log(`[Heartbeat] Sent #${heartbeatCount} for session ${SESSION_ID}`);
-      }
-    } else {
-      heartbeatCount--; // Rollback count on failure
-      failureCount++;
-      console.error(`[Heartbeat] Failed (${response.status}): ${await response.text()}`);
-
-      if (failureCount >= MAX_FAILURES) {
-        console.error(`[Heartbeat] Max failures reached (${MAX_FAILURES}), stopping`);
-        await cleanup();
-      }
-    }
-  } catch (error) {
-    heartbeatCount--; // Rollback count on error
-    failureCount++;
-    console.error(`[Heartbeat] Error sending heartbeat:`, error.message);
-
-    if (failureCount >= MAX_FAILURES) {
-      console.error(`[Heartbeat] Max failures reached (${MAX_FAILURES}), stopping`);
-      await cleanup();
-    }
-  }
-}
-
-/**
- * Cleanup and exit
- */
-async function cleanup() {
-  console.log(`[Heartbeat] Cleaning up session ${SESSION_ID}`);
-
-  if (intervalHandle) {
-    clearInterval(intervalHandle);
-    intervalHandle = null;
-  }
-
-  // Remove PID file
-  try {
-    await unlink(PID_FILE);
-  } catch (error) {
-    // Ignore errors - file might not exist
-  }
-
-  exit(0);
-}
-
-/**
- * Start heartbeat loop
- */
-async function start() {
-  try {
-    // Write PID file with session_id for validation (prevents killing wrong process)
-    await writeFile(PID_FILE, JSON.stringify({
-      pid: processPid,
-      session_id: SESSION_ID,
-      started_at: Date.now()
-    }), { mode: 0o600 });
-
-    if (DEBUG) {
-      console.log(`[Heartbeat] Started for session ${SESSION_ID} (PID: ${processPid})`);
-      console.log(`[Heartbeat] Interval: ${HEARTBEAT_INTERVAL}ms, Start delay: ${START_DELAY}ms, Max failures: ${MAX_FAILURES}, Fetch timeout: ${FETCH_TIMEOUT}ms`);
-    }
-
-    // Wait for initial delay before first heartbeat
-    setTimeout(() => {
-      // Send first heartbeat immediately after delay
-      sendHeartbeat();
-
-      // Then set up interval for subsequent heartbeats
-      intervalHandle = setInterval(sendHeartbeat, HEARTBEAT_INTERVAL);
-    }, START_DELAY);
-
-    // Handle graceful shutdown
-    process.on('SIGTERM', cleanup);
-    process.on('SIGINT', cleanup);
-    process.on('SIGHUP', cleanup);
-
-  } catch (error) {
-    console.error(`[Heartbeat] Failed to start:`, error.message);
-    exit(1);
-  }
-}
-
-// Start the heartbeat process
-start();

package/lib/daemon/pid-manager.js

@@ -1,183 +0,0 @@
-import { promises as fs } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
-
-/**
- * PID Manager
- * Manages daemon process ID file for ensuring single daemon instance
- */
-
-export const TELEPORTATION_DIR = join(homedir(), '.teleportation');
-export const PID_FILE = join(TELEPORTATION_DIR, 'daemon.pid');
-
-/**
- * Check if a process with given PID is running
- */
-export function isProcessRunning(pid) {
-  console.log(`[pid-manager] Checking if process ${pid} is running...`);
-  // Handle invalid PIDs
-  if (typeof pid !== 'number' || pid <= 0) {
-    return false;
-  }
-
-  try {
-    // Signal 0 checks if process exists without actually sending a signal
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return false;
-  }
-}
-
-/**
- * Read PID from file
- * @returns {Promise<number|null>} PID or null if file doesn't exist or is invalid
- */
-export async function readPid() {
-  console.log(`[pid-manager] Reading PID from ${PID_FILE}...`);
-  try {
-    const content = await fs.readFile(PID_FILE, 'utf-8');
-    const pid = parseInt(content.trim(), 10);
-    if (isNaN(pid) || pid <= 0) {
-      return null;
-    }
-    return pid;
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      return null;
-    }
-    throw err;
-  }
-}
-
-/**
- * Write PID to file with 600 permissions
- * @param {number} pid - Process ID to write
- */
-export async function writePid(pid) {
-  console.log(`[pid-manager] Writing PID ${pid} to ${PID_FILE}...`);
-  // Ensure .teleportation directory exists
-  await fs.mkdir(TELEPORTATION_DIR, { recursive: true, mode: 0o700 });
-
-  // Write PID file with 600 permissions (owner read/write only)
-  await fs.writeFile(PID_FILE, String(pid), { mode: 0o600 });
-}
-
-/**
- * Remove PID file
- */
-export async function removePid() {
-  console.log(`[pid-manager] Removing PID file ${PID_FILE}...`);
-  try {
-    await fs.unlink(PID_FILE);
-  } catch (err) {
-    if (err.code !== 'ENOENT') {
-      throw err;
-    }
-  }
-}
-
-/**
- * Check if daemon is already running
- * @returns {Promise<{running: boolean, pid: number|null, stale: boolean}>}
- */
-export async function checkDaemonStatus() {
-  const pid = await readPid();
-
-  if (pid === null) {
-    return { running: false, pid: null, stale: false };
-  }
-
-  const running = isProcessRunning(pid);
-
-  return {
-    running,
-    pid,
-    stale: !running // PID file exists but process is dead
-  };
-}
-
-/**
- * Clean up stale PID file (when process doesn't exist)
- * @returns {Promise<boolean>} true if stale PID was removed
- */
-export async function cleanupStalePid() {
-  const status = await checkDaemonStatus();
-
-  if (status.stale) {
-    await removePid();
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Acquire PID lock (write PID file, ensuring no other daemon is running)
- * @param {number} pid - Process ID to write
- * @throws {Error} if another daemon is already running
- */
-export async function acquirePidLock(pid) {
-  console.log(`[pid-manager] Acquiring PID lock for PID ${pid}...`);
-  
-  // Ensure .teleportation directory exists with strict permissions
-  await fs.mkdir(TELEPORTATION_DIR, { recursive: true, mode: 0o700 });
-
-  // 1. Attempt atomic acquisition with 'wx' (exclusive write)
-  try {
-    await fs.writeFile(PID_FILE, String(pid), { mode: 0o600, flag: 'wx' });
-    return;
-  } catch (err) {
-    if (err.code !== 'EEXIST') {
-      throw err;
-    }
-    
-    // 2. Lock exists - verify if it's stale
-    const currentPid = await readPid();
-    
-    if (currentPid === null) {
-      // Should not happen with atomic write, but handles concurrent removal
-      return await acquirePidLock(pid);
-    }
-
-    if (currentPid === pid) {
-      // Self-recovery: we already own this lock
-      return;
-    }
-
-    if (isProcessRunning(currentPid)) {
-      throw new Error(`Daemon already running with PID ${currentPid}`);
-    }
-
-    // 3. Process dead - stale lock. Clean up and retry.
-    console.log(`[pid-manager] Stale PID file found (${currentPid}), cleaning up and retrying...`);
-    await removePid();
-    return await acquirePidLock(pid);
-  }
-}
-
-/**
- * Release PID lock (remove PID file if it matches our PID)
- * @param {number} pid - Our process ID
- */
-export async function releasePidLock(pid) {
-  console.log(`[pid-manager] Releasing PID lock for PID ${pid}...`);
-  const currentPid = await readPid();
-
-  // Only remove if PID file matches our process
-  if (currentPid === pid) {
-    await removePid();
-  }
-}
-
-export default {
-  isProcessRunning,
-  readPid,
-  writePid,
-  removePid,
-  checkDaemonStatus,
-  cleanupStalePid,
-  acquirePidLock,
-  releasePidLock,
-  PID_FILE
-};