scene-capability-engine 3.0.0

package/lib/lock/lock-manager.js

@@ -0,0 +1,321 @@
+/**
+ * LockManager - Manages Spec locks for multi-user collaboration
+ * @module lib/lock/lock-manager
+ */
+
+const path = require('path');
+const os = require('os');
+const { LockFile } = require('./lock-file');
+const { MachineIdentifier } = require('./machine-identifier');
+
+const DEFAULT_TIMEOUT_HOURS = 24;
+const MAX_RETRY_COUNT = 3;
+const RETRY_DELAY_MS = 100;
+
+class LockManager {
+  /**
+   * @param {string} workspaceRoot - Root directory of the workspace
+   * @param {MachineIdentifier} [machineIdentifier] - Machine ID provider
+   */
+  constructor(workspaceRoot, machineIdentifier = null) {
+    this.workspaceRoot = workspaceRoot;
+    this.specsDir = path.join(workspaceRoot, '.kiro', 'specs');
+    this.configDir = path.join(workspaceRoot, '.kiro', 'config');
+    this.lockFile = new LockFile(this.specsDir);
+    this.machineIdentifier = machineIdentifier || new MachineIdentifier(this.configDir);
+  }
+
+  /**
+   * Acquire a lock on a Spec
+   * @param {string} specName - Name of the Spec to lock
+   * @param {Object} options - Lock options
+   * @param {string} [options.reason] - Reason for acquiring the lock
+   * @param {number} [options.timeout] - Lock timeout in hours (default: 24)
+   * @returns {Promise<LockResult>}
+   */
+  async acquireLock(specName, options = {}) {
+    const { reason = null, timeout = DEFAULT_TIMEOUT_HOURS } = options;
+
+    // Check if spec directory exists
+    const specDir = path.join(this.specsDir, specName);
+    try {
+      const fs = require('fs').promises;
+      await fs.access(specDir);
+    } catch {
+      return { success: false, error: 'Spec not found' };
+    }
+
+    // Check existing lock with retry for concurrent access
+    for (let attempt = 0; attempt < MAX_RETRY_COUNT; attempt++) {
+      const existingLock = await this.lockFile.read(specName);
+      
+      if (existingLock) {
+        const machineId = await this.machineIdentifier.getMachineId();
+        if (existingLock.machineId === machineId.id) {
+          // Already locked by this machine - update the lock
+          const lock = await this._createLockMetadata(reason, timeout);
+          await this.lockFile.write(specName, lock);
+          return { success: true, lock };
+        }
+        return {
+          success: false,
+          error: 'Spec is already locked',
+          existingLock
+        };
+      }
+
+      // Try to acquire lock
+      try {
+        const lock = await this._createLockMetadata(reason, timeout);
+        await this.lockFile.write(specName, lock);
+        
+        // Verify we got the lock (handle race condition)
+        const verifyLock = await this.lockFile.read(specName);
+        const machineId = await this.machineIdentifier.getMachineId();
+        
+        if (verifyLock && verifyLock.machineId === machineId.id) {
+          return { success: true, lock };
+        }
+        
+        // Someone else got the lock
+        return {
+          success: false,
+          error: 'Spec is already locked',
+          existingLock: verifyLock
+        };
+      } catch (error) {
+        if (attempt < MAX_RETRY_COUNT - 1) {
+          await this._delay(RETRY_DELAY_MS * Math.pow(2, attempt));
+          continue;
+        }
+        throw error;
+      }
+    }
+
+    return { success: false, error: 'Failed to acquire lock after retries' };
+  }
+
+
+  /**
+   * Release a lock on a Spec
+   * @param {string} specName - Name of the Spec to unlock
+   * @param {Object} options - Unlock options
+   * @param {boolean} [options.force] - Force unlock regardless of ownership
+   * @returns {Promise<UnlockResult>}
+   */
+  async releaseLock(specName, options = {}) {
+    const { force = false } = options;
+
+    const existingLock = await this.lockFile.read(specName);
+    
+    if (!existingLock) {
+      return { success: true, message: 'No lock exists on this Spec' };
+    }
+
+    const machineId = await this.machineIdentifier.getMachineId();
+    
+    if (existingLock.machineId !== machineId.id && !force) {
+      return {
+        success: false,
+        error: 'Lock owned by different machine',
+        existingLock
+      };
+    }
+
+    const deleted = await this.lockFile.delete(specName);
+    
+    return {
+      success: true,
+      forced: force && existingLock.machineId !== machineId.id,
+      previousLock: existingLock
+    };
+  }
+
+  /**
+   * Get lock status for a specific Spec or all Specs
+   * @param {string} [specName] - Optional Spec name, if omitted returns all locks
+   * @returns {Promise<LockStatus|LockStatus[]>}
+   */
+  async getLockStatus(specName) {
+    if (specName) {
+      return this._getSingleLockStatus(specName);
+    }
+    return this._getAllLockStatus();
+  }
+
+  /**
+   * Get lock status for a single spec
+   * @param {string} specName
+   * @returns {Promise<LockStatus>}
+   * @private
+   */
+  async _getSingleLockStatus(specName) {
+    const lock = await this.lockFile.read(specName);
+    const machineId = await this.machineIdentifier.getMachineId();
+    
+    if (!lock) {
+      return { specName, locked: false };
+    }
+
+    return {
+      specName,
+      locked: true,
+      lock,
+      isStale: this._isStale(lock),
+      isOwnedByMe: lock.machineId === machineId.id,
+      duration: this._formatDuration(lock.timestamp)
+    };
+  }
+
+  /**
+   * Get lock status for all specs
+   * @returns {Promise<LockStatus[]>}
+   * @private
+   */
+  async _getAllLockStatus() {
+    const lockedSpecs = await this.lockFile.listLockedSpecs();
+    const statuses = [];
+    
+    for (const specName of lockedSpecs) {
+      const status = await this._getSingleLockStatus(specName);
+      statuses.push(status);
+    }
+    
+    return statuses;
+  }
+
+  /**
+   * Clean up stale locks
+   * @returns {Promise<CleanupResult>}
+   */
+  async cleanupStaleLocks() {
+    const result = { cleaned: 0, cleanedLocks: [], errors: [] };
+    const lockedSpecs = await this.lockFile.listLockedSpecs();
+    
+    for (const specName of lockedSpecs) {
+      try {
+        const lock = await this.lockFile.read(specName);
+        if (lock && this._isStale(lock)) {
+          await this.lockFile.delete(specName);
+          result.cleaned++;
+          result.cleanedLocks.push({ specName, lock });
+        }
+      } catch (error) {
+        result.errors.push({ specName, error: error.message });
+      }
+    }
+    
+    return result;
+  }
+
+  /**
+   * Check if a Spec is locked
+   * @param {string} specName - Name of the Spec
+   * @returns {Promise<boolean>}
+   */
+  async isLocked(specName) {
+    return this.lockFile.exists(specName);
+  }
+
+  /**
+   * Check if current machine owns the lock
+   * @param {string} specName - Name of the Spec
+   * @returns {Promise<boolean>}
+   */
+  async isLockedByMe(specName) {
+    const lock = await this.lockFile.read(specName);
+    if (!lock) return false;
+    
+    const machineId = await this.machineIdentifier.getMachineId();
+    return lock.machineId === machineId.id;
+  }
+
+
+  /**
+   * Create lock metadata
+   * @param {string|null} reason
+   * @param {number} timeout
+   * @returns {Promise<LockMetadata>}
+   * @private
+   */
+  async _createLockMetadata(reason, timeout) {
+    const machineId = await this.machineIdentifier.getMachineId();
+    const owner = this._getOwnerName();
+    
+    return {
+      owner,
+      machineId: machineId.id,
+      hostname: machineId.hostname,
+      timestamp: new Date().toISOString(),
+      reason: reason || null,
+      timeout,
+      version: '1.0.0'
+    };
+  }
+
+  /**
+   * Get owner name from git config or environment
+   * @returns {string}
+   * @private
+   */
+  _getOwnerName() {
+    try {
+      const { execSync } = require('child_process');
+      const gitUser = execSync('git config user.name', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
+      if (gitUser) return gitUser;
+    } catch {
+      // Git not available or not configured
+    }
+    
+    try {
+      return os.userInfo().username || process.env.USER || process.env.USERNAME || 'unknown';
+    } catch {
+      return process.env.USER || process.env.USERNAME || 'unknown';
+    }
+  }
+
+  /**
+   * Check if a lock is stale
+   * @param {LockMetadata} lock
+   * @returns {boolean}
+   * @private
+   */
+  _isStale(lock) {
+    const lockTime = new Date(lock.timestamp).getTime();
+    const now = Date.now();
+    const timeoutMs = lock.timeout * 60 * 60 * 1000;
+    return (now - lockTime) > timeoutMs;
+  }
+
+  /**
+   * Format duration since lock was acquired
+   * @param {string} timestamp
+   * @returns {string}
+   * @private
+   */
+  _formatDuration(timestamp) {
+    const lockTime = new Date(timestamp).getTime();
+    const now = Date.now();
+    const diffMs = now - lockTime;
+    
+    const hours = Math.floor(diffMs / (1000 * 60 * 60));
+    const minutes = Math.floor((diffMs % (1000 * 60 * 60)) / (1000 * 60));
+    
+    if (hours > 0) {
+      return `${hours}h ${minutes}m`;
+    }
+    return `${minutes}m`;
+  }
+
+  /**
+   * Delay helper for retry logic
+   * @param {number} ms
+   * @returns {Promise<void>}
+   * @private
+   */
+  _delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+module.exports = { LockManager, DEFAULT_TIMEOUT_HOURS };

package/lib/lock/machine-identifier.js

@@ -0,0 +1,135 @@
+/**
+ * MachineIdentifier - Provides unique machine identification for lock ownership
+ * @module lib/lock/machine-identifier
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+class MachineIdentifier {
+  /**
+   * @param {string} configDir - Directory for storing machine ID
+   */
+  constructor(configDir) {
+    this.configDir = configDir;
+    this.configFile = path.join(configDir, 'machine-id.json');
+    this._cachedId = null;
+  }
+
+  /**
+   * Get the current machine's identifier
+   * @returns {Promise<MachineId>}
+   */
+  async getMachineId() {
+    if (this._cachedId) {
+      return this._cachedId;
+    }
+
+    try {
+      const data = await fs.readFile(this.configFile, 'utf8');
+      const machineId = JSON.parse(data);
+      if (this._isValidMachineId(machineId)) {
+        this._cachedId = machineId;
+        return machineId;
+      }
+    } catch (error) {
+      // File doesn't exist or is corrupted, generate new ID
+    }
+
+    const newId = this.generateMachineId();
+    await this._persistMachineId(newId);
+    this._cachedId = newId;
+    return newId;
+  }
+
+  /**
+   * Generate a new machine ID
+   * @returns {MachineId}
+   */
+  generateMachineId() {
+    const hostname = this._getHostname();
+    const uuid = crypto.randomUUID();
+    
+    return {
+      id: `${hostname}-${uuid}`,
+      hostname: hostname,
+      createdAt: new Date().toISOString()
+    };
+  }
+
+  /**
+   * Get human-readable machine info
+   * @returns {Promise<MachineInfo>}
+   */
+  async getMachineInfo() {
+    const machineId = await this.getMachineId();
+    return {
+      id: machineId.id,
+      hostname: machineId.hostname,
+      createdAt: machineId.createdAt,
+      platform: os.platform(),
+      user: this._getUsername()
+    };
+  }
+
+  /**
+   * Get hostname safely
+   * @returns {string}
+   * @private
+   */
+  _getHostname() {
+    try {
+      return os.hostname() || 'unknown-host';
+    } catch {
+      return 'unknown-host';
+    }
+  }
+
+  /**
+   * Get username safely
+   * @returns {string}
+   * @private
+   */
+  _getUsername() {
+    try {
+      return os.userInfo().username || process.env.USER || process.env.USERNAME || 'unknown-user';
+    } catch {
+      return process.env.USER || process.env.USERNAME || 'unknown-user';
+    }
+  }
+
+  /**
+   * Validate machine ID structure
+   * @param {Object} machineId
+   * @returns {boolean}
+   * @private
+   */
+  _isValidMachineId(machineId) {
+    return (
+      machineId &&
+      typeof machineId.id === 'string' &&
+      typeof machineId.hostname === 'string' &&
+      typeof machineId.createdAt === 'string' &&
+      machineId.id.length > 0
+    );
+  }
+
+  /**
+   * Persist machine ID to config file
+   * @param {MachineId} machineId
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _persistMachineId(machineId) {
+    try {
+      await fs.mkdir(this.configDir, { recursive: true });
+      await fs.writeFile(this.configFile, JSON.stringify(machineId, null, 2), 'utf8');
+    } catch (error) {
+      console.warn(`Warning: Could not persist machine ID: ${error.message}`);
+    }
+  }
+}
+
+module.exports = { MachineIdentifier };

package/lib/lock/steering-file-lock.js

@@ -0,0 +1,207 @@
+/**
+ * SteeringFileLock - Protects concurrent writes to Steering files
+ *
+ * Uses file-level locks with exclusive create (`wx`) to serialize writes
+ * to `.kiro/steering/` files. When lock acquisition fails after retries,
+ * falls back to writing a pending file for later merge.
+ *
+ * Lock file path: `.kiro/steering/{filename}.lock`
+ * Pending file path: `.kiro/steering/{filename}.pending.{agentId}`
+ *
+ * Requirements: 5.1, 5.2, 5.3, 5.4
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const crypto = require('crypto');
+const fsUtils = require('../utils/fs-utils');
+
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 100;
+const STALE_LOCK_MS = 30000; // 30 seconds
+
+class SteeringFileLock {
+  /**
+   * @param {string} workspaceRoot - Absolute path to the project root
+   */
+  constructor(workspaceRoot) {
+    this._workspaceRoot = workspaceRoot;
+    this._steeringDir = path.join(workspaceRoot, '.kiro', 'steering');
+  }
+
+  /**
+   * Lock file path for a given steering filename.
+   * @param {string} filename
+   * @returns {string}
+   * @private
+   */
+  _lockPath(filename) {
+    return path.join(this._steeringDir, `${filename}.lock`);
+  }
+
+  /**
+   * Acquire a write lock for a Steering file.
+   * Retries up to MAX_RETRIES times with exponential backoff (Req 5.2).
+   *
+   * @param {string} filename - Steering filename (e.g. "CURRENT_CONTEXT.md")
+   * @returns {Promise<{success: boolean, lockId?: string, error?: string}>}
+   */
+  async acquireLock(filename) {
+    const lockFile = this._lockPath(filename);
+    const lockId = crypto.randomUUID();
+    const lockData = JSON.stringify({
+      lockId,
+      acquiredAt: new Date().toISOString(),
+    });
+
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      if (attempt > 0) {
+        const delayMs = BASE_DELAY_MS * Math.pow(2, attempt - 1);
+        await this._sleep(delayMs);
+      }
+
+      try {
+        await fsUtils.ensureDirectory(this._steeringDir);
+        await fs.writeFile(lockFile, lockData, { flag: 'wx' });
+        return { success: true, lockId };
+      } catch (err) {
+        if (err.code === 'EEXIST') {
+          // Lock held — check for staleness
+          const claimed = await this._tryClaimStaleLock(lockFile, lockData);
+          if (claimed) {
+            return { success: true, lockId };
+          }
+          continue; // retry
+        }
+        throw err;
+      }
+    }
+
+    return { success: false, error: 'Failed to acquire lock: retries exhausted' };
+  }
+
+  /**
+   * Release a previously acquired write lock.
+   * Only the holder (matching lockId) can release the lock.
+   *
+   * @param {string} filename - Steering filename
+   * @param {string} lockId - The lockId returned by acquireLock
+   * @returns {Promise<{success: boolean, error?: string}>}
+   */
+  async releaseLock(filename, lockId) {
+    const lockFile = this._lockPath(filename);
+
+    try {
+      const raw = await fs.readFile(lockFile, 'utf8');
+      const data = JSON.parse(raw);
+
+      if (data.lockId !== lockId) {
+        return { success: false, error: 'Lock owned by different caller' };
+      }
+
+      await fs.unlink(lockFile);
+      return { success: true };
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        // Lock already gone — treat as success
+        return { success: true };
+      }
+      if (err instanceof SyntaxError) {
+        // Corrupted lock file — remove it
+        try { await fs.unlink(lockFile); } catch (_) { /* ignore */ }
+        return { success: true };
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Execute a callback while holding the Steering file lock.
+   * Acquires the lock, runs the callback, then releases the lock.
+   * If lock acquisition fails, throws an error.
+   *
+   * @param {string} filename - Steering filename
+   * @param {Function} callback - async () => result
+   * @returns {Promise<*>} The callback's return value
+   */
+  async withLock(filename, callback) {
+    const { success, lockId, error } = await this.acquireLock(filename);
+    if (!success) {
+      throw new Error(error || 'Failed to acquire steering file lock');
+    }
+
+    try {
+      return await callback();
+    } finally {
+      await this.releaseLock(filename, lockId);
+    }
+  }
+
+  /**
+   * Write content to a pending file as a fallback when lock acquisition fails.
+   * Pending file path: `.kiro/steering/{filename}.pending.{agentId}`
+   * Uses atomic write for file integrity (Req 5.3, 5.4).
+   *
+   * @param {string} filename - Steering filename
+   * @param {string} content - Content to write
+   * @param {string} agentId - Agent identifier
+   * @returns {Promise<{pendingPath: string}>}
+   */
+  async writePending(filename, content, agentId) {
+    await fsUtils.ensureDirectory(this._steeringDir);
+    const pendingPath = path.join(this._steeringDir, `${filename}.pending.${agentId}`);
+    await fsUtils.atomicWrite(pendingPath, content);
+    return { pendingPath };
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────────
+
+  /**
+   * If the existing lock file is older than STALE_LOCK_MS, remove it and
+   * re-attempt acquisition.
+   *
+   * @param {string} lockFile
+   * @param {string} lockData
+   * @returns {Promise<boolean>}
+   * @private
+   */
+  async _tryClaimStaleLock(lockFile, lockData) {
+    try {
+      const stat = await fs.stat(lockFile);
+      const ageMs = Date.now() - stat.mtimeMs;
+      if (ageMs > STALE_LOCK_MS) {
+        await fs.unlink(lockFile);
+        try {
+          await fs.writeFile(lockFile, lockData, { flag: 'wx' });
+          return true;
+        } catch (retryErr) {
+          if (retryErr.code === 'EEXIST') return false;
+          throw retryErr;
+        }
+      }
+    } catch (statErr) {
+      if (statErr.code === 'ENOENT') {
+        try {
+          await fs.writeFile(lockFile, lockData, { flag: 'wx' });
+          return true;
+        } catch (retryErr) {
+          if (retryErr.code === 'EEXIST') return false;
+          throw retryErr;
+        }
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Promise-based sleep helper.
+   * @param {number} ms
+   * @returns {Promise<void>}
+   * @private
+   */
+  _sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+module.exports = { SteeringFileLock };