@vibecheckai/cli 3.2.5 → 3.3.0

package/mcp-server/conductor/lock-manager.js

@@ -0,0 +1,615 @@
+/**
+ * Conductor Lock Manager
+ * 
+ * Manages file-level and folder-level locks for multi-agent coordination.
+ * Prevents concurrent modifications and detects deadlocks.
+ * 
+ * Codename: Conductor
+ */
+
+"use strict";
+
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { conductorLogger as log, getErrorMessage } from "../logger.js";
+
+/**
+ * @typedef {Object} Lock
+ * @property {string} lockId - Unique lock ID
+ * @property {string} path - Locked path (file or folder)
+ * @property {string} type - Lock type (exclusive, shared)
+ * @property {string} sessionId - Owning session ID
+ * @property {string} agentId - Owning agent ID
+ * @property {Date} acquiredAt - When lock was acquired
+ * @property {Date} expiresAt - When lock expires
+ * @property {string} reason - Reason for lock
+ */
+
+/**
+ * Lock types
+ */
+const LOCK_TYPES = {
+  EXCLUSIVE: "exclusive",  // Write lock - only one holder
+  SHARED: "shared",        // Read lock - multiple holders allowed
+};
+
+/**
+ * Default lock timeout (5 minutes)
+ */
+const DEFAULT_LOCK_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Lock Manager class
+ */
+class LockManager {
+  constructor(options = {}) {
+    this.locks = new Map(); // lockId -> Lock
+    this.pathLocks = new Map(); // normalizedPath -> Set<lockId>
+    this.sessionLocks = new Map(); // sessionId -> Set<lockId>
+    this.lockTimeout = options.lockTimeout || DEFAULT_LOCK_TIMEOUT_MS;
+    this.persistPath = options.persistPath || null;
+    
+    // Cleanup interval
+    this.cleanupInterval = setInterval(() => {
+      this.cleanupExpiredLocks();
+    }, 30000); // Check every 30 seconds
+    
+    // Load persisted state
+    if (this.persistPath) {
+      this.loadState();
+    }
+  }
+  
+  /**
+   * Generate a unique lock ID
+   * @returns {string} Lock ID
+   */
+  generateLockId() {
+    return `lock_${crypto.randomBytes(8).toString("hex")}`;
+  }
+  
+  /**
+   * Normalize a file path for consistent comparison
+   * @param {string} filePath - Path to normalize
+   * @returns {string} Normalized path
+   */
+  normalizePath(filePath) {
+    return path.resolve(filePath).replace(/\\/g, "/").toLowerCase();
+  }
+  
+  /**
+   * Check if a path is a parent of another
+   * @param {string} parent - Potential parent path
+   * @param {string} child - Potential child path
+   * @returns {boolean} Is parent
+   */
+  isParentPath(parent, child) {
+    const normalizedParent = this.normalizePath(parent);
+    const normalizedChild = this.normalizePath(child);
+    
+    if (normalizedParent === normalizedChild) return true;
+    
+    return normalizedChild.startsWith(normalizedParent + "/");
+  }
+  
+  /**
+   * Get all locks that conflict with a path
+   * @param {string} filePath - Path to check
+   * @param {string} lockType - Type of lock being requested
+   * @returns {Lock[]} Conflicting locks
+   */
+  getConflictingLocks(filePath, lockType) {
+    const normalizedPath = this.normalizePath(filePath);
+    const conflicts = [];
+    
+    for (const lock of this.locks.values()) {
+      // Check if lock is expired
+      if (this.isLockExpired(lock)) continue;
+      
+      const lockPath = this.normalizePath(lock.path);
+      
+      // Check for path overlap
+      const pathOverlap = this.isParentPath(lockPath, normalizedPath) || 
+                          this.isParentPath(normalizedPath, lockPath);
+      
+      if (!pathOverlap) continue;
+      
+      // Shared locks don't conflict with other shared locks
+      if (lockType === LOCK_TYPES.SHARED && lock.type === LOCK_TYPES.SHARED) {
+        continue;
+      }
+      
+      conflicts.push(lock);
+    }
+    
+    return conflicts;
+  }
+  
+  /**
+   * Acquire a lock
+   * @param {Object} params - Lock parameters
+   * @returns {Object} Result with lock or conflict info
+   */
+  acquireLock({
+    path: filePath,
+    type = LOCK_TYPES.EXCLUSIVE,
+    sessionId,
+    agentId,
+    reason = "",
+    timeout = null,
+  }) {
+    const normalizedPath = this.normalizePath(filePath);
+    
+    // Check for conflicting locks
+    const conflicts = this.getConflictingLocks(filePath, type);
+    
+    // Filter out locks owned by the same session
+    const externalConflicts = conflicts.filter(l => l.sessionId !== sessionId);
+    
+    if (externalConflicts.length > 0) {
+      return {
+        acquired: false,
+        conflict: true,
+        conflictingLocks: externalConflicts,
+        message: `Path is locked by ${externalConflicts.length} other session(s)`,
+      };
+    }
+    
+    // Check if this session already has a lock on this path
+    const existingLock = this.getSessionLockForPath(sessionId, filePath);
+    if (existingLock) {
+      // Upgrade lock if needed (shared -> exclusive)
+      if (existingLock.type === LOCK_TYPES.SHARED && type === LOCK_TYPES.EXCLUSIVE) {
+        existingLock.type = LOCK_TYPES.EXCLUSIVE;
+        existingLock.expiresAt = new Date(Date.now() + (timeout || this.lockTimeout));
+        this.saveState();
+        return {
+          acquired: true,
+          upgraded: true,
+          lock: existingLock,
+        };
+      }
+      
+      // Refresh existing lock
+      existingLock.expiresAt = new Date(Date.now() + (timeout || this.lockTimeout));
+      this.saveState();
+      return {
+        acquired: true,
+        refreshed: true,
+        lock: existingLock,
+      };
+    }
+    
+    // Create new lock
+    const lockId = this.generateLockId();
+    const now = new Date();
+    
+    const lock = {
+      lockId,
+      path: normalizedPath,
+      type,
+      sessionId,
+      agentId,
+      acquiredAt: now,
+      expiresAt: new Date(now.getTime() + (timeout || this.lockTimeout)),
+      reason,
+    };
+    
+    // Store lock
+    this.locks.set(lockId, lock);
+    
+    // Index by path
+    if (!this.pathLocks.has(normalizedPath)) {
+      this.pathLocks.set(normalizedPath, new Set());
+    }
+    this.pathLocks.get(normalizedPath).add(lockId);
+    
+    // Index by session
+    if (!this.sessionLocks.has(sessionId)) {
+      this.sessionLocks.set(sessionId, new Set());
+    }
+    this.sessionLocks.get(sessionId).add(lockId);
+    
+    // Persist state
+    this.saveState();
+    
+    return {
+      acquired: true,
+      lock,
+    };
+  }
+  
+  /**
+   * Release a lock
+   * @param {string} lockId - Lock ID to release
+   * @param {string} sessionId - Session ID (for validation)
+   * @returns {boolean} Success
+   */
+  releaseLock(lockId, sessionId = null) {
+    const lock = this.locks.get(lockId);
+    if (!lock) return false;
+    
+    // Validate session if provided
+    if (sessionId && lock.sessionId !== sessionId) {
+      return false;
+    }
+    
+    // Remove from locks
+    this.locks.delete(lockId);
+    
+    // Remove from path index
+    const pathLocks = this.pathLocks.get(lock.path);
+    if (pathLocks) {
+      pathLocks.delete(lockId);
+      if (pathLocks.size === 0) {
+        this.pathLocks.delete(lock.path);
+      }
+    }
+    
+    // Remove from session index
+    const sessionLocks = this.sessionLocks.get(lock.sessionId);
+    if (sessionLocks) {
+      sessionLocks.delete(lockId);
+      if (sessionLocks.size === 0) {
+        this.sessionLocks.delete(lock.sessionId);
+      }
+    }
+    
+    // Persist state
+    this.saveState();
+    
+    return true;
+  }
+  
+  /**
+   * Release all locks for a session
+   * @param {string} sessionId - Session ID
+   * @returns {number} Number of locks released
+   */
+  releaseSessionLocks(sessionId) {
+    const sessionLockIds = this.sessionLocks.get(sessionId);
+    if (!sessionLockIds) return 0;
+    
+    const lockIds = Array.from(sessionLockIds);
+    let released = 0;
+    
+    for (const lockId of lockIds) {
+      if (this.releaseLock(lockId)) {
+        released++;
+      }
+    }
+    
+    return released;
+  }
+  
+  /**
+   * Get a session's lock for a specific path
+   * @param {string} sessionId - Session ID
+   * @param {string} filePath - File path
+   * @returns {Lock|null} Lock or null
+   */
+  getSessionLockForPath(sessionId, filePath) {
+    const sessionLockIds = this.sessionLocks.get(sessionId);
+    if (!sessionLockIds) return null;
+    
+    const normalizedPath = this.normalizePath(filePath);
+    
+    for (const lockId of sessionLockIds) {
+      const lock = this.locks.get(lockId);
+      if (lock && lock.path === normalizedPath && !this.isLockExpired(lock)) {
+        return lock;
+      }
+    }
+    
+    return null;
+  }
+  
+  /**
+   * Get all locks for a path
+   * @param {string} filePath - File path
+   * @returns {Lock[]} Locks
+   */
+  getLocksForPath(filePath) {
+    const normalizedPath = this.normalizePath(filePath);
+    const lockIds = this.pathLocks.get(normalizedPath);
+    if (!lockIds) return [];
+    
+    const locks = [];
+    for (const lockId of lockIds) {
+      const lock = this.locks.get(lockId);
+      if (lock && !this.isLockExpired(lock)) {
+        locks.push(lock);
+      }
+    }
+    
+    return locks;
+  }
+  
+  /**
+   * Get all locks for a session
+   * @param {string} sessionId - Session ID
+   * @returns {Lock[]} Locks
+   */
+  getSessionLocks(sessionId) {
+    const lockIds = this.sessionLocks.get(sessionId);
+    if (!lockIds) return [];
+    
+    const locks = [];
+    for (const lockId of lockIds) {
+      const lock = this.locks.get(lockId);
+      if (lock && !this.isLockExpired(lock)) {
+        locks.push(lock);
+      }
+    }
+    
+    return locks;
+  }
+  
+  /**
+   * Check if a lock is expired
+   * @param {Lock} lock - Lock to check
+   * @returns {boolean} Is expired
+   */
+  isLockExpired(lock) {
+    return new Date(lock.expiresAt).getTime() < Date.now();
+  }
+  
+  /**
+   * Refresh a lock's expiration
+   * @param {string} lockId - Lock ID
+   * @param {string} sessionId - Session ID (for validation)
+   * @returns {Lock|null} Refreshed lock or null
+   */
+  refreshLock(lockId, sessionId = null) {
+    const lock = this.locks.get(lockId);
+    if (!lock) return null;
+    
+    if (sessionId && lock.sessionId !== sessionId) {
+      return null;
+    }
+    
+    lock.expiresAt = new Date(Date.now() + this.lockTimeout);
+    this.saveState();
+    
+    return lock;
+  }
+  
+  /**
+   * Detect potential deadlocks
+   * @returns {Object[]} Potential deadlock situations
+   */
+  detectDeadlocks() {
+    const deadlocks = [];
+    const sessionDeps = new Map(); // sessionId -> Set<sessionId> (waiting on)
+    
+    // Build dependency graph
+    for (const lock of this.locks.values()) {
+      if (this.isLockExpired(lock)) continue;
+      
+      // Find sessions waiting for this lock
+      // (This is a simplified detection - in practice, you'd track actual wait queues)
+      const conflicts = this.getConflictingLocks(lock.path, LOCK_TYPES.EXCLUSIVE);
+      
+      for (const conflict of conflicts) {
+        if (conflict.sessionId !== lock.sessionId) {
+          if (!sessionDeps.has(lock.sessionId)) {
+            sessionDeps.set(lock.sessionId, new Set());
+          }
+          sessionDeps.get(lock.sessionId).add(conflict.sessionId);
+        }
+      }
+    }
+    
+    // Detect cycles using DFS
+    const visited = new Set();
+    const inStack = new Set();
+    
+    const dfs = (sessionId, path) => {
+      if (inStack.has(sessionId)) {
+        // Found cycle
+        const cycleStart = path.indexOf(sessionId);
+        deadlocks.push({
+          type: "cycle",
+          sessions: path.slice(cycleStart),
+        });
+        return;
+      }
+      
+      if (visited.has(sessionId)) return;
+      
+      visited.add(sessionId);
+      inStack.add(sessionId);
+      path.push(sessionId);
+      
+      const deps = sessionDeps.get(sessionId);
+      if (deps) {
+        for (const dep of deps) {
+          dfs(dep, [...path]);
+        }
+      }
+      
+      inStack.delete(sessionId);
+    };
+    
+    for (const sessionId of sessionDeps.keys()) {
+      if (!visited.has(sessionId)) {
+        dfs(sessionId, []);
+      }
+    }
+    
+    return deadlocks;
+  }
+  
+  /**
+   * Force release a lock (admin operation)
+   * @param {string} lockId - Lock ID
+   * @param {string} reason - Reason for force release
+   * @returns {boolean} Success
+   */
+  forceReleaseLock(lockId, reason = "Admin force release") {
+    const lock = this.locks.get(lockId);
+    if (!lock) return false;
+    
+    log.warn(`Force releasing lock ${lockId}: ${reason}`);
+    
+    return this.releaseLock(lockId);
+  }
+  
+  /**
+   * Cleanup expired locks
+   */
+  cleanupExpiredLocks() {
+    const expiredIds = [];
+    
+    for (const [lockId, lock] of this.locks) {
+      if (this.isLockExpired(lock)) {
+        expiredIds.push(lockId);
+      }
+    }
+    
+    for (const lockId of expiredIds) {
+      this.releaseLock(lockId);
+    }
+    
+    if (expiredIds.length > 0) {
+      log.info(`Cleaned up ${expiredIds.length} expired locks`);
+    }
+  }
+  
+  /**
+   * Get lock statistics
+   * @returns {Object} Statistics
+   */
+  getStatistics() {
+    let exclusiveCount = 0;
+    let sharedCount = 0;
+    let expiredCount = 0;
+    
+    for (const lock of this.locks.values()) {
+      if (this.isLockExpired(lock)) {
+        expiredCount++;
+      } else if (lock.type === LOCK_TYPES.EXCLUSIVE) {
+        exclusiveCount++;
+      } else {
+        sharedCount++;
+      }
+    }
+    
+    return {
+      totalLocks: this.locks.size,
+      exclusiveLocks: exclusiveCount,
+      sharedLocks: sharedCount,
+      expiredLocks: expiredCount,
+      lockedPaths: this.pathLocks.size,
+      sessionsWithLocks: this.sessionLocks.size,
+    };
+  }
+  
+  /**
+   * Save state to disk
+   */
+  saveState() {
+    if (!this.persistPath) return;
+    
+    try {
+      const dir = path.dirname(this.persistPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      
+      const state = {
+        locks: Array.from(this.locks.entries()),
+        timestamp: new Date().toISOString(),
+      };
+      
+      fs.writeFileSync(this.persistPath, JSON.stringify(state, null, 2));
+    } catch (error) {
+      log.warn(`Failed to save lock state: ${getErrorMessage(error)}`);
+    }
+  }
+  
+  /**
+   * Load state from disk
+   */
+  loadState() {
+    if (!this.persistPath || !fs.existsSync(this.persistPath)) return;
+    
+    try {
+      const content = fs.readFileSync(this.persistPath, "utf-8");
+      const state = JSON.parse(content);
+      
+      for (const [lockId, lock] of state.locks || []) {
+        // Convert date strings
+        lock.acquiredAt = new Date(lock.acquiredAt);
+        lock.expiresAt = new Date(lock.expiresAt);
+        
+        // Only restore non-expired locks
+        if (!this.isLockExpired(lock)) {
+          this.locks.set(lockId, lock);
+          
+          // Rebuild path index
+          if (!this.pathLocks.has(lock.path)) {
+            this.pathLocks.set(lock.path, new Set());
+          }
+          this.pathLocks.get(lock.path).add(lockId);
+          
+          // Rebuild session index
+          if (!this.sessionLocks.has(lock.sessionId)) {
+            this.sessionLocks.set(lock.sessionId, new Set());
+          }
+          this.sessionLocks.get(lock.sessionId).add(lockId);
+        }
+      }
+      
+      log.info(`Restored ${this.locks.size} locks from disk`);
+    } catch (error) {
+      log.warn(`Failed to load lock state: ${getErrorMessage(error)}`);
+    }
+  }
+  
+  /**
+   * Shutdown the lock manager
+   */
+  shutdown() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+    }
+    this.saveState();
+  }
+}
+
+/**
+ * Create a lock manager instance
+ * @param {Object} options - Options
+ * @returns {LockManager} Manager instance
+ */
+function createLockManager(options = {}) {
+  return new LockManager(options);
+}
+
+// Default instance
+let defaultManager = null;
+
+/**
+ * Get the default lock manager
+ * @param {string} projectRoot - Project root for persist path
+ * @returns {LockManager} Default manager
+ */
+function getLockManager(projectRoot) {
+  if (!defaultManager) {
+    const persistPath = projectRoot 
+      ? path.join(projectRoot, ".vibecheck", "conductor", "locks.json")
+      : null;
+    defaultManager = createLockManager({ persistPath });
+  }
+  return defaultManager;
+}
+
+export {
+  LockManager,
+  createLockManager,
+  getLockManager,
+  LOCK_TYPES,
+  DEFAULT_LOCK_TIMEOUT_MS,
+};