scene-capability-engine 3.0.0

package/lib/collab/merge-coordinator.js

@@ -0,0 +1,252 @@
+/**
+ * Merge Coordinator - Manages Agent Git branches and merge operations
+ *
+ * Handles branch creation, conflict detection, auto-merge, and cleanup
+ * for multi-Agent parallel coordination. In single-Agent mode, all
+ * branch operations are skipped (agents work on the current branch).
+ *
+ * Branch naming: `agent/{agentId}/{specName}`
+ *
+ * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6
+ */
+
+const { execSync } = require('child_process');
+const { MultiAgentConfig } = require('./multi-agent-config');
+
+/** Default options for execSync Git commands */
+const EXEC_OPTS = Object.freeze({
+  encoding: 'utf8',
+  stdio: ['pipe', 'pipe', 'pipe'],
+});
+
+class MergeCoordinator {
+  /**
+   * @param {string} workspaceRoot - Absolute path to the project root
+   */
+  constructor(workspaceRoot) {
+    this._workspaceRoot = workspaceRoot;
+    this._multiAgentConfig = new MultiAgentConfig(workspaceRoot);
+  }
+
+  /**
+   * Execute a Git command in the workspace root.
+   * @param {string} command - Git command (without the leading `git `)
+   * @returns {string} Trimmed stdout
+   * @private
+   */
+  _git(command) {
+    return execSync(`git ${command}`, {
+      ...EXEC_OPTS,
+      cwd: this._workspaceRoot,
+    }).trim();
+  }
+
+  /**
+   * Whether multi-Agent mode is enabled.
+   * In single-Agent mode all branch operations are skipped (Req 4.6).
+   * @returns {Promise<boolean>}
+   */
+  async isMultiAgentMode() {
+    return this._multiAgentConfig.isEnabled();
+  }
+
+  /**
+   * Create an agent-specific branch from the current HEAD.
+   * Branch name follows the format `agent/{agentId}/{specName}` (Req 4.1).
+   *
+   * In single-Agent mode, returns the current branch name without creating
+   * a new branch (Req 4.6).
+   *
+   * @param {string} agentId
+   * @param {string} specName
+   * @returns {Promise<{branchName: string, created: boolean}>}
+   */
+  async createAgentBranch(agentId, specName) {
+    const multiAgent = await this.isMultiAgentMode();
+    if (!multiAgent) {
+      // Single-Agent mode – stay on the current branch (Req 4.6)
+      const current = this._getCurrentBranch();
+      return { branchName: current, created: false };
+    }
+
+    const branchName = `agent/${agentId}/${specName}`;
+
+    try {
+      // Check if branch already exists
+      this._git(`rev-parse --verify refs/heads/${branchName}`);
+      // Branch exists – just switch to it
+      this._git(`checkout ${branchName}`);
+      return { branchName, created: false };
+    } catch (_err) {
+      // Branch does not exist – create it from current HEAD
+      try {
+        this._git(`checkout -b ${branchName}`);
+        return { branchName, created: true };
+      } catch (createErr) {
+        throw new Error(
+          `Failed to create agent branch "${branchName}": ${createErr.message}`
+        );
+      }
+    }
+  }
+
+  /**
+   * Detect merge conflicts between a branch and a target branch (Req 4.2).
+   *
+   * Uses `git merge --no-commit --no-ff` followed by `git merge --abort`
+   * to perform a dry-run merge without altering the working tree permanently.
+   *
+   * @param {string} branchName - Source branch to merge
+   * @param {string} targetBranch - Target branch (e.g. "main")
+   * @returns {Promise<{hasConflicts: boolean, files: string[]}>}
+   */
+  async detectConflicts(branchName, targetBranch) {
+    const multiAgent = await this.isMultiAgentMode();
+    if (!multiAgent) {
+      return { hasConflicts: false, files: [] };
+    }
+
+    // Save current branch so we can restore it
+    const originalBranch = this._getCurrentBranch();
+
+    try {
+      // Switch to target branch for the trial merge
+      this._git(`checkout ${targetBranch}`);
+
+      try {
+        this._git(`merge --no-commit --no-ff ${branchName}`);
+        // Merge succeeded without conflicts – abort to undo
+        this._safeAbortMerge();
+        return { hasConflicts: false, files: [] };
+      } catch (_mergeErr) {
+        // Merge had conflicts – collect conflicting files
+        const files = this._getConflictFiles();
+        this._safeAbortMerge();
+        return { hasConflicts: true, files };
+      }
+    } finally {
+      // Always restore the original branch
+      try {
+        this._git(`checkout ${originalBranch}`);
+      } catch (_restoreErr) {
+        // Best-effort restore; nothing more we can do
+      }
+    }
+  }
+
+  /**
+   * Execute a merge of branchName into targetBranch (Req 4.3, 4.4).
+   *
+   * When no conflicts exist, performs a fast-forward merge if possible,
+   * otherwise creates a merge commit. When conflicts exist, records the
+   * conflict details and returns them without modifying the target branch.
+   *
+   * @param {string} branchName - Source branch to merge
+   * @param {string} targetBranch - Target branch
+   * @returns {Promise<{success: boolean, strategy: string|null, conflicts: string[]}>}
+   */
+  async merge(branchName, targetBranch) {
+    const multiAgent = await this.isMultiAgentMode();
+    if (!multiAgent) {
+      return { success: true, strategy: 'single-agent-noop', conflicts: [] };
+    }
+
+    const originalBranch = this._getCurrentBranch();
+
+    try {
+      this._git(`checkout ${targetBranch}`);
+
+      // Try fast-forward first
+      try {
+        this._git(`merge --ff-only ${branchName}`);
+        return { success: true, strategy: 'fast-forward', conflicts: [] };
+      } catch (_ffErr) {
+        // Fast-forward not possible – try regular merge
+      }
+
+      try {
+        this._git(`merge ${branchName} -m "Merge ${branchName} into ${targetBranch}"`);
+        return { success: true, strategy: 'merge-commit', conflicts: [] };
+      } catch (_mergeErr) {
+        // Conflicts detected (Req 4.4)
+        const conflicts = this._getConflictFiles();
+        this._safeAbortMerge();
+        return { success: false, strategy: null, conflicts };
+      }
+    } finally {
+      try {
+        this._git(`checkout ${originalBranch}`);
+      } catch (_restoreErr) {
+        // Best-effort restore
+      }
+    }
+  }
+
+  /**
+   * Delete a branch that has already been merged (Req 4.5).
+   *
+   * Uses `git branch -d` which only succeeds if the branch is fully merged.
+   *
+   * @param {string} branchName
+   * @returns {Promise<{success: boolean, error: string|null}>}
+   */
+  async cleanupBranch(branchName) {
+    const multiAgent = await this.isMultiAgentMode();
+    if (!multiAgent) {
+      return { success: true, error: null };
+    }
+
+    try {
+      this._git(`branch -d ${branchName}`);
+      return { success: true, error: null };
+    } catch (err) {
+      return {
+        success: false,
+        error: `Failed to delete branch "${branchName}": ${err.message}`,
+      };
+    }
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────
+
+  /**
+   * Get the name of the currently checked-out branch.
+   * @returns {string}
+   * @private
+   */
+  _getCurrentBranch() {
+    try {
+      return this._git('rev-parse --abbrev-ref HEAD');
+    } catch (_err) {
+      return 'HEAD'; // detached HEAD or not a git repo
+    }
+  }
+
+  /**
+   * Collect the list of files with merge conflicts from `git diff --name-only --diff-filter=U`.
+   * @returns {string[]}
+   * @private
+   */
+  _getConflictFiles() {
+    try {
+      const output = this._git('diff --name-only --diff-filter=U');
+      return output ? output.split('\n').filter(Boolean) : [];
+    } catch (_err) {
+      return [];
+    }
+  }
+
+  /**
+   * Safely abort a merge in progress. Swallows errors if no merge is active.
+   * @private
+   */
+  _safeAbortMerge() {
+    try {
+      this._git('merge --abort');
+    } catch (_err) {
+      // No merge to abort – that's fine
+    }
+  }
+}
+
+module.exports = { MergeCoordinator };

package/lib/collab/metadata-manager.js

@@ -0,0 +1,233 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+/**
+ * MetadataManager handles CRUD operations on collaboration.json files
+ * Provides atomic updates and schema validation
+ */
+class MetadataManager {
+  constructor(workspaceRoot) {
+    this.workspaceRoot = workspaceRoot;
+    this.specsDir = path.join(workspaceRoot, '.kiro', 'specs');
+  }
+
+  /**
+   * Read collaboration metadata for a spec
+   * @param {string} specName - Name of the spec
+   * @returns {Promise<Object|null>} Metadata object or null if not found
+   */
+  async readMetadata(specName) {
+    const metadataPath = this._getMetadataPath(specName);
+    
+    try {
+      const content = await fs.readFile(metadataPath, 'utf8');
+      return JSON.parse(content);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return null;
+      }
+      throw new Error(`Failed to read metadata for ${specName}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Write collaboration metadata for a spec
+   * @param {string} specName - Name of the spec
+   * @param {Object} metadata - Metadata object to write
+   * @returns {Promise<void>}
+   */
+  async writeMetadata(specName, metadata) {
+    // Validate metadata before writing
+    this.validateMetadata(metadata);
+    
+    const metadataPath = this._getMetadataPath(specName);
+    const specDir = path.dirname(metadataPath);
+    
+    // Ensure spec directory exists
+    await fs.mkdir(specDir, { recursive: true });
+    
+    // Write with pretty formatting
+    const content = JSON.stringify(metadata, null, 2);
+    await fs.writeFile(metadataPath, content, 'utf8');
+  }
+
+  /**
+   * Validate metadata against schema
+   * @param {Object} metadata - Metadata to validate
+   * @throws {Error} If metadata is invalid
+   */
+  validateMetadata(metadata) {
+    if (!metadata || typeof metadata !== 'object') {
+      throw new Error('Metadata must be an object');
+    }
+
+    // Required fields
+    if (!metadata.version) {
+      throw new Error('Missing required field: version');
+    }
+
+    
+    if (!metadata.type || !['master', 'sub'].includes(metadata.type)) {
+      throw new Error('Invalid or missing type: must be "master" or "sub"');
+    }
+
+    // Validate dependencies array
+    if (metadata.dependencies) {
+      if (!Array.isArray(metadata.dependencies)) {
+        throw new Error('dependencies must be an array');
+      }
+      
+      for (const dep of metadata.dependencies) {
+        if (!dep.spec || typeof dep.spec !== 'string') {
+          throw new Error('Each dependency must have a spec name');
+        }
+        
+        if (!dep.type || !['requires-completion', 'requires-interface', 'optional'].includes(dep.type)) {
+          throw new Error(`Invalid dependency type: ${dep.type}`);
+        }
+      }
+    }
+
+    // Validate status
+    if (metadata.status) {
+      const validStatuses = ['not-started', 'in-progress', 'completed', 'blocked'];
+      if (!metadata.status.current || !validStatuses.includes(metadata.status.current)) {
+        throw new Error(`Invalid status: ${metadata.status.current}`);
+      }
+      
+      if (!metadata.status.updatedAt) {
+        throw new Error('Status must have updatedAt timestamp');
+      }
+    }
+
+    // Validate interfaces
+    if (metadata.interfaces) {
+      if (!Array.isArray(metadata.interfaces.provides)) {
+        throw new Error('interfaces.provides must be an array');
+      }
+      if (!Array.isArray(metadata.interfaces.consumes)) {
+        throw new Error('interfaces.consumes must be an array');
+      }
+    }
+  }
+
+  /**
+   * Delete collaboration metadata for a spec
+   * @param {string} specName - Name of the spec
+   * @returns {Promise<boolean>} True if deleted, false if not found
+   */
+  async deleteMetadata(specName) {
+    const metadataPath = this._getMetadataPath(specName);
+    
+    try {
+      await fs.unlink(metadataPath);
+      return true;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return false;
+      }
+      throw new Error(`Failed to delete metadata for ${specName}: ${error.message}`);
+    }
+  }
+
+  /**
+   * List all specs with collaboration metadata
+   * @returns {Promise<Array<{name: string, metadata: Object}>>}
+   */
+  async listAllMetadata() {
+    const specs = [];
+    
+    try {
+      const specDirs = await fs.readdir(this.specsDir);
+      
+      for (const specName of specDirs) {
+        const metadata = await this.readMetadata(specName);
+        if (metadata) {
+          specs.push({ name: specName, metadata });
+        }
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return [];
+      }
+      throw error;
+    }
+    
+    return specs;
+  }
+
+  /**
+   * Perform atomic update on metadata
+   * @param {string} specName - Name of the spec
+   * @param {Function} updateFn - Function that receives current metadata and returns updated metadata
+   * @returns {Promise<Object>} Updated metadata
+   */
+  async atomicUpdate(specName, updateFn) {
+    const maxRetries = 3;
+    let lastError;
+    
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        // Read current metadata
+        const current = await this.readMetadata(specName) || this._getDefaultMetadata();
+        
+        // Apply update function
+        const updated = await updateFn(current);
+        
+        // Write updated metadata
+        await this.writeMetadata(specName, updated);
+        
+        return updated;
+      } catch (error) {
+        lastError = error;
+        
+        // Exponential backoff
+        if (attempt < maxRetries - 1) {
+          await this._sleep(Math.pow(2, attempt) * 100);
+        }
+      }
+    }
+    
+    throw new Error(`Atomic update failed after ${maxRetries} attempts: ${lastError.message}`);
+  }
+
+  /**
+   * Get default metadata structure
+   * @returns {Object}
+   */
+  _getDefaultMetadata() {
+    return {
+      version: '1.0.0',
+      type: 'sub',
+      dependencies: [],
+      status: {
+        current: 'not-started',
+        updatedAt: new Date().toISOString()
+      },
+      interfaces: {
+        provides: [],
+        consumes: []
+      }
+    };
+  }
+
+  /**
+   * Get metadata file path for a spec
+   * @param {string} specName
+   * @returns {string}
+   */
+  _getMetadataPath(specName) {
+    return path.join(this.specsDir, specName, 'collaboration.json');
+  }
+
+  /**
+   * Sleep for specified milliseconds
+   * @param {number} ms
+   * @returns {Promise<void>}
+   */
+  _sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+module.exports = MetadataManager;

package/lib/collab/multi-agent-config.js

@@ -0,0 +1,120 @@
+/**
+ * Multi-Agent Configuration Manager
+ *
+ * Manages `.kiro/config/multi-agent.json` for multi-Agent parallel coordination.
+ * When the config file does not exist or is corrupted, returns a default
+ * disabled configuration so that single-Agent mode is completely unaffected.
+ *
+ * Requirements: 7.1 (no extra files when disabled), 7.4 (auto-init on first enable)
+ */
+
+const path = require('path');
+const fsUtils = require('../utils/fs-utils');
+
+const CONFIG_FILENAME = 'multi-agent.json';
+const CONFIG_DIR = '.kiro/config';
+
+/** @type {import('./multi-agent-config').MultiAgentConfigData} */
+const DEFAULT_CONFIG = Object.freeze({
+  enabled: false,
+  heartbeatIntervalMs: 60000,
+  heartbeatTimeoutMs: 180000,
+  coordinatorEnabled: false,
+  maxRetries: 5,
+  retryBaseDelayMs: 100,
+});
+
+class MultiAgentConfig {
+  /**
+   * @param {string} workspaceRoot - Absolute path to the project root
+   */
+  constructor(workspaceRoot) {
+    this._workspaceRoot = workspaceRoot;
+    this._configPath = path.join(workspaceRoot, CONFIG_DIR, CONFIG_FILENAME);
+    this._configDir = path.join(workspaceRoot, CONFIG_DIR);
+  }
+
+  /**
+   * Read the current configuration.
+   * Returns the default (disabled) config when the file is missing or corrupted.
+   *
+   * @returns {Promise<object>} Resolved configuration
+   */
+  async getConfig() {
+    const exists = await fsUtils.pathExists(this._configPath);
+    if (!exists) {
+      return { ...DEFAULT_CONFIG };
+    }
+
+    try {
+      const data = await fsUtils.readJSON(this._configPath);
+      return { ...DEFAULT_CONFIG, ...data };
+    } catch (_err) {
+      // Corrupted JSON – fall back to defaults with a warning
+      console.warn(
+        `[MultiAgentConfig] Failed to parse ${this._configPath}, using default config`
+      );
+      return { ...DEFAULT_CONFIG };
+    }
+  }
+
+  /**
+   * Whether multi-Agent mode is enabled.
+   * @returns {Promise<boolean>}
+   */
+  async isEnabled() {
+    const config = await this.getConfig();
+    return config.enabled === true;
+  }
+
+  /**
+   * Whether the central coordinator is enabled.
+   * Only meaningful when multi-Agent mode itself is enabled.
+   * @returns {Promise<boolean>}
+   */
+  async isCoordinatorEnabled() {
+    const config = await this.getConfig();
+    return config.enabled === true && config.coordinatorEnabled === true;
+  }
+
+  /**
+   * Persist a (partial) configuration update.
+   * Merges the provided values with the current config and writes atomically.
+   * Auto-initialises the config directory on first write (Requirement 7.4).
+   *
+   * @param {object} updates - Partial config values to merge
+   * @returns {Promise<object>} The full config after the update
+   */
+  async updateConfig(updates) {
+    await fsUtils.ensureDirectory(this._configDir);
+    const current = await this.getConfig();
+    const merged = { ...current, ...updates };
+    await fsUtils.writeJSON(this._configPath, merged);
+    return merged;
+  }
+
+  /**
+   * Enable multi-Agent mode.
+   * Convenience wrapper that also initialises the required directory structure.
+   *
+   * @returns {Promise<object>} The full config after enabling
+   */
+  async enable() {
+    return this.updateConfig({ enabled: true });
+  }
+
+  /**
+   * Disable multi-Agent mode.
+   * @returns {Promise<object>} The full config after disabling
+   */
+  async disable() {
+    return this.updateConfig({ enabled: false });
+  }
+
+  /** Absolute path to the config file (useful for tests / diagnostics). */
+  get configPath() {
+    return this._configPath;
+  }
+}
+
+module.exports = { MultiAgentConfig, DEFAULT_CONFIG };