scene-capability-engine 3.0.0

package/lib/upgrade/migration-engine.js

@@ -0,0 +1,382 @@
+/**
+ * Migration Engine
+ * 
+ * Manages version upgrades by planning and executing migration scripts.
+ * Handles incremental upgrades through intermediate versions.
+ */
+
+const path = require('path');
+const { pathExists, readJSON } = require('../utils/fs-utils');
+const VersionManager = require('../version/version-manager');
+const GitignoreIntegration = require('../gitignore/gitignore-integration');
+
+class MigrationEngine {
+  constructor() {
+    this.versionManager = new VersionManager();
+    this.migrationsDir = path.join(__dirname, 'migrations');
+  }
+
+  /**
+   * Plans upgrade from current to target version
+   * 
+   * @param {string} fromVersion - Current version
+   * @param {string} toVersion - Target version
+   * @returns {Promise<UpgradePlan>}
+   */
+  async planUpgrade(fromVersion, toVersion) {
+    try {
+      // Calculate upgrade path
+      const upgradePath = this.versionManager.calculateUpgradePath(fromVersion, toVersion);
+      
+      // Build list of migrations needed
+      const migrations = [];
+      for (let i = 0; i < upgradePath.length - 1; i++) {
+        const from = upgradePath[i];
+        const to = upgradePath[i + 1];
+        
+        // Check if migration script exists
+        const migrationScript = await this.findMigrationScript(from, to);
+        
+        // Check compatibility
+        const compatibility = this.versionManager.checkCompatibility(from, to);
+        
+        migrations.push({
+          from,
+          to,
+          breaking: compatibility.breaking,
+          script: migrationScript,
+          required: compatibility.migration === 'required'
+        });
+      }
+      
+      // Estimate time (rough estimate: 10 seconds per migration)
+      const estimatedTime = migrations.length > 0 
+        ? `${migrations.length * 10} seconds`
+        : '< 5 seconds';
+      
+      return {
+        fromVersion,
+        toVersion,
+        path: upgradePath,
+        migrations,
+        estimatedTime,
+        backupRequired: true
+      };
+    } catch (error) {
+      throw new Error(`Failed to plan upgrade: ${error.message}`);
+    }
+  }
+
+  /**
+   * Executes upgrade plan
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @param {UpgradePlan} plan - Upgrade plan from planUpgrade()
+   * @param {Object} options - Upgrade options
+   * @param {boolean} options.dryRun - If true, don't make changes
+   * @param {Function} options.onProgress - Progress callback (step, total, message)
+   * @returns {Promise<UpgradeResult>}
+   */
+  async executeUpgrade(projectPath, plan, options = {}) {
+    const { dryRun = false, onProgress = null } = options;
+    
+    const migrationsExecuted = [];
+    const errors = [];
+    const warnings = [];
+    
+    try {
+      // Read current version info
+      const versionInfo = await this.versionManager.readVersion(projectPath);
+      if (!versionInfo) {
+        throw new Error('version.json not found');
+      }
+      
+      // Verify starting version matches plan
+      if (versionInfo['kse-version'] !== plan.fromVersion) {
+        throw new Error(
+          `Version mismatch: expected ${plan.fromVersion}, found ${versionInfo['kse-version']}`
+        );
+      }
+      
+      if (dryRun) {
+        return {
+          success: true,
+          fromVersion: plan.fromVersion,
+          toVersion: plan.toVersion,
+          migrationsExecuted: plan.migrations.map(m => ({
+            from: m.from,
+            to: m.to,
+            success: true,
+            changes: ['(dry-run) No changes made'],
+            error: null
+          })),
+          backupId: null,
+          errors: [],
+          warnings: ['Dry run - no changes made']
+        };
+      }
+      
+      // Execute migrations sequentially
+      for (let i = 0; i < plan.migrations.length; i++) {
+        const migration = plan.migrations[i];
+        
+        if (onProgress) {
+          onProgress(i + 1, plan.migrations.length, `Migrating ${migration.from} → ${migration.to}`);
+        }
+        
+        try {
+          // Load migration script if it exists
+          let migrationResult = {
+            from: migration.from,
+            to: migration.to,
+            success: true,
+            changes: [],
+            error: null
+          };
+          
+          if (migration.script) {
+            // Execute migration script
+            const script = await this.loadMigration(migration.from, migration.to);
+            
+            if (script) {
+              const result = await script.migrate(projectPath, {
+                fromVersion: migration.from,
+                toVersion: migration.to,
+                versionInfo
+              });
+              
+              migrationResult.changes = result.changes || [];
+            } else {
+              migrationResult.changes.push('No migration script needed');
+            }
+          } else {
+            migrationResult.changes.push('No migration script needed');
+          }
+          
+          // Update version info
+          this.versionManager.addUpgradeHistory(
+            versionInfo,
+            migration.from,
+            migration.to,
+            true
+          );
+          
+          // Write updated version info
+          await this.versionManager.writeVersion(projectPath, versionInfo);
+          
+          migrationsExecuted.push(migrationResult);
+        } catch (error) {
+          // Migration failed - record error and stop
+          const migrationResult = {
+            from: migration.from,
+            to: migration.to,
+            success: false,
+            changes: [],
+            error: error.message
+          };
+          
+          migrationsExecuted.push(migrationResult);
+          errors.push(`Migration ${migration.from} → ${migration.to} failed: ${error.message}`);
+          
+          // Add failed upgrade to history
+          this.versionManager.addUpgradeHistory(
+            versionInfo,
+            migration.from,
+            migration.to,
+            false,
+            error.message
+          );
+          await this.versionManager.writeVersion(projectPath, versionInfo);
+          
+          // Stop execution on first failure
+          throw new Error(`Migration failed: ${error.message}`);
+        }
+      }
+      
+      // Fix .gitignore for team collaboration after successful upgrade
+      try {
+        const gitignoreIntegration = new GitignoreIntegration();
+        const gitignoreResult = await gitignoreIntegration.integrateWithUpgrade(projectPath);
+        
+        if (gitignoreResult.success && gitignoreResult.action !== 'skipped') {
+          warnings.push(gitignoreResult.message);
+        } else if (!gitignoreResult.success) {
+          warnings.push(`⚠️  .gitignore fix failed: ${gitignoreResult.message}`);
+          warnings.push('You can fix this manually with: kse doctor --fix-gitignore');
+        }
+      } catch (gitignoreError) {
+        // Don't block upgrade on .gitignore fix failure
+        warnings.push(`⚠️  .gitignore check failed: ${gitignoreError.message}`);
+        warnings.push('You can fix this manually with: kse doctor --fix-gitignore');
+      }
+      
+      return {
+        success: true,
+        fromVersion: plan.fromVersion,
+        toVersion: plan.toVersion,
+        migrationsExecuted,
+        backupId: null, // Backup ID should be set by caller
+        errors,
+        warnings
+      };
+    } catch (error) {
+      return {
+        success: false,
+        fromVersion: plan.fromVersion,
+        toVersion: plan.toVersion,
+        migrationsExecuted,
+        backupId: null,
+        errors: [error.message, ...errors],
+        warnings
+      };
+    }
+  }
+
+  /**
+   * Loads migration script for version transition
+   * 
+   * @param {string} fromVersion - Source version
+   * @param {string} toVersion - Target version
+   * @returns {Promise<MigrationScript|null>}
+   */
+  async loadMigration(fromVersion, toVersion) {
+    try {
+      const scriptPath = await this.findMigrationScript(fromVersion, toVersion);
+      
+      if (!scriptPath) {
+        return null;
+      }
+      
+      // Load the migration script
+      const script = require(scriptPath);
+      
+      // Validate script interface
+      if (!script.migrate || typeof script.migrate !== 'function') {
+        throw new Error(`Invalid migration script: missing migrate() function`);
+      }
+      
+      return script;
+    } catch (error) {
+      throw new Error(`Failed to load migration script: ${error.message}`);
+    }
+  }
+
+  /**
+   * Finds migration script file for version transition
+   * 
+   * @param {string} fromVersion - Source version
+   * @param {string} toVersion - Target version
+   * @returns {Promise<string|null>} - Absolute path to script or null if not found
+   */
+  async findMigrationScript(fromVersion, toVersion) {
+    // Try different naming conventions
+    const possibleNames = [
+      `${fromVersion}-to-${toVersion}.js`,
+      `${fromVersion}_to_${toVersion}.js`,
+      `v${fromVersion}-to-v${toVersion}.js`
+    ];
+    
+    for (const name of possibleNames) {
+      const scriptPath = path.join(this.migrationsDir, name);
+      const exists = await pathExists(scriptPath);
+      
+      if (exists) {
+        return scriptPath;
+      }
+    }
+    
+    return null;
+  }
+
+  /**
+   * Validates upgrade result
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {Promise<ValidationResult>}
+   */
+  async validate(projectPath) {
+    const errors = [];
+    const warnings = [];
+    
+    try {
+      // Check if .kiro/ directory exists
+      const kiroPath = path.join(projectPath, '.kiro');
+      const kiroExists = await pathExists(kiroPath);
+      
+      if (!kiroExists) {
+        errors.push('.kiro/ directory not found');
+        return { success: false, errors, warnings };
+      }
+      
+      // Check if version.json exists and is valid
+      const versionInfo = await this.versionManager.readVersion(projectPath);
+      
+      if (!versionInfo) {
+        errors.push('version.json not found or invalid');
+        return { success: false, errors, warnings };
+      }
+      
+      // Check required directories
+      const requiredDirs = ['specs', 'steering', 'tools', 'backups'];
+      
+      for (const dir of requiredDirs) {
+        const dirPath = path.join(kiroPath, dir);
+        const exists = await pathExists(dirPath);
+        
+        if (!exists) {
+          warnings.push(`${dir}/ directory not found`);
+        }
+      }
+      
+      // Check required steering files
+      const requiredSteeringFiles = [
+        'steering/CORE_PRINCIPLES.md',
+        'steering/ENVIRONMENT.md',
+        'steering/CURRENT_CONTEXT.md',
+        'steering/RULES_GUIDE.md'
+      ];
+      
+      for (const file of requiredSteeringFiles) {
+        const filePath = path.join(kiroPath, file);
+        const exists = await pathExists(filePath);
+        
+        if (!exists) {
+          warnings.push(`${file} not found`);
+        }
+      }
+      
+      return {
+        success: errors.length === 0,
+        errors,
+        warnings
+      };
+    } catch (error) {
+      errors.push(`Validation failed: ${error.message}`);
+      return { success: false, errors, warnings };
+    }
+  }
+
+  /**
+   * Gets available migrations
+   * 
+   * @returns {Promise<string[]>} - Array of migration script names
+   */
+  async getAvailableMigrations() {
+    try {
+      const exists = await pathExists(this.migrationsDir);
+      
+      if (!exists) {
+        return [];
+      }
+      
+      const fs = require('fs-extra');
+      const files = await fs.readdir(this.migrationsDir);
+      
+      return files.filter(file => file.endsWith('.js'));
+    } catch (error) {
+      return [];
+    }
+  }
+}
+
+module.exports = MigrationEngine;

package/lib/upgrade/migrations/.gitkeep

@@ -0,0 +1,52 @@
+# Migration Scripts Directory
+
+This directory contains migration scripts for upgrading between versions.
+
+## Migration Script Format
+
+Each migration script should follow this format:
+
+```javascript
+module.exports = {
+  version: "1.1.0",
+  breaking: false,
+  description: "Description of what this migration does",
+  
+  /**
+   * Executes migration
+   * @param {string} projectPath - Absolute path to project root
+   * @param {MigrationContext} context - Migration context
+   * @returns {Promise<MigrationResult>}
+   */
+  async migrate(projectPath, context) {
+    const changes = [];
+    
+    // Migration logic here
+    // Example: Update file structure, modify configs, etc.
+    
+    return {
+      success: true,
+      changes
+    };
+  },
+  
+  /**
+   * Rolls back migration (optional)
+   * @param {string} projectPath - Absolute path to project root
+   * @param {MigrationContext} context - Migration context
+   * @returns {Promise<void>}
+   */
+  async rollback(projectPath, context) {
+    // Rollback logic here
+  }
+};
+```
+
+## Naming Convention
+
+Migration scripts should be named: `{fromVersion}-to-{toVersion}.js`
+
+Examples:
+- `1.0.0-to-1.1.0.js`
+- `1.1.0-to-1.2.0.js`
+- `1.2.0-to-2.0.0.js`

package/lib/upgrade/migrations/1.0.0-to-1.1.0.js

@@ -0,0 +1,78 @@
+/**
+ * Migration: 1.0.0 → 1.1.0
+ * 
+ * Adds version management foundation:
+ * - Ensures version.json exists with correct structure
+ * - Adds backups/ directory if missing
+ * - No breaking changes
+ */
+
+const path = require('path');
+const { pathExists, ensureDirectory, writeJSON } = require('../../utils/fs-utils');
+
+module.exports = {
+  version: "1.1.0",
+  breaking: false,
+  description: "Add version management foundation (version.json, backups/)",
+  
+  /**
+   * Executes migration from 1.0.0 to 1.1.0
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @param {MigrationContext} context - Migration context
+   * @returns {Promise<MigrationResult>}
+   */
+  async migrate(projectPath, context) {
+    const changes = [];
+    
+    try {
+      const kiroPath = path.join(projectPath, '.kiro');
+      
+      // 1. Ensure backups/ directory exists
+      const backupsPath = path.join(kiroPath, 'backups');
+      const backupsExists = await pathExists(backupsPath);
+      
+      if (!backupsExists) {
+        await ensureDirectory(backupsPath);
+        changes.push('Created backups/ directory');
+      }
+      
+      // 2. Ensure version.json has correct structure
+      // (This is handled by VersionManager, but we verify it here)
+      const versionPath = path.join(kiroPath, 'version.json');
+      const versionExists = await pathExists(versionPath);
+      
+      if (versionExists) {
+        changes.push('Verified version.json structure');
+      } else {
+        changes.push('version.json will be created by VersionManager');
+      }
+      
+      // 3. Add any other 1.1.0-specific changes here
+      // (None for this version - it's just the foundation)
+      
+      return {
+        success: true,
+        changes
+      };
+    } catch (error) {
+      throw new Error(`Migration 1.0.0 → 1.1.0 failed: ${error.message}`);
+    }
+  },
+  
+  /**
+   * Rolls back migration from 1.1.0 to 1.0.0
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @param {MigrationContext} context - Migration context
+   * @returns {Promise<void>}
+   */
+  async rollback(projectPath, context) {
+    // For 1.0.0 → 1.1.0, rollback is simple:
+    // - Remove backups/ directory (but keep backups for safety)
+    // - version.json will be handled by VersionManager
+    
+    // Note: We don't actually remove anything to preserve data safety
+    // The backup system will handle restoration if needed
+  }
+};

package/lib/utils/file-diff.js

@@ -0,0 +1,177 @@
+/**
+ * File Diff Utility
+ * 
+ * Provides file comparison and diff detection functionality
+ */
+
+const fs = require('fs-extra');
+const crypto = require('crypto');
+const path = require('path');
+
+class FileDiff {
+  /**
+   * Calculate file hash
+   * 
+   * @param {string} filePath - Path to file
+   * @param {string} algorithm - Hash algorithm (default: 'md5')
+   * @returns {Promise<string>} File hash
+   */
+  async calculateHash(filePath, algorithm = 'md5') {
+    if (!await fs.pathExists(filePath)) {
+      return null;
+    }
+    
+    const content = await fs.readFile(filePath);
+    return crypto.createHash(algorithm).update(content).digest('hex');
+  }
+  
+  /**
+   * Compare two files by content
+   * 
+   * @param {string} file1Path - Path to first file
+   * @param {string} file2Path - Path to second file
+   * @returns {Promise<boolean>} True if files are identical
+   */
+  async areFilesIdentical(file1Path, file2Path) {
+    // Check if both files exist
+    const file1Exists = await fs.pathExists(file1Path);
+    const file2Exists = await fs.pathExists(file2Path);
+    
+    if (!file1Exists || !file2Exists) {
+      return false;
+    }
+    
+    // Compare file sizes first (quick check)
+    const stat1 = await fs.stat(file1Path);
+    const stat2 = await fs.stat(file2Path);
+    
+    if (stat1.size !== stat2.size) {
+      return false;
+    }
+    
+    // Compare content hashes
+    const hash1 = await this.calculateHash(file1Path);
+    const hash2 = await this.calculateHash(file2Path);
+    
+    return hash1 === hash2;
+  }
+  
+  /**
+   * Compare multiple file pairs
+   * 
+   * @param {Array<{source: string, target: string}>} filePairs - Array of file pairs to compare
+   * @param {string} projectRoot - Project root path
+   * @returns {Promise<Object>} Comparison results
+   */
+  async compareFiles(filePairs, projectRoot) {
+    const results = {
+      identical: [],      // Files with same content
+      different: [],      // Files with different content
+      newFiles: [],       // Files that don't exist in target
+      errors: []          // Files that couldn't be compared
+    };
+    
+    for (const pair of filePairs) {
+      try {
+        const sourcePath = path.isAbsolute(pair.source) 
+          ? pair.source 
+          : path.join(projectRoot, pair.source);
+        const targetPath = path.isAbsolute(pair.target)
+          ? pair.target
+          : path.join(projectRoot, pair.target);
+        
+        const targetExists = await fs.pathExists(targetPath);
+        
+        if (!targetExists) {
+          results.newFiles.push({
+            source: pair.source,
+            target: pair.target,
+            reason: 'Target file does not exist'
+          });
+          continue;
+        }
+        
+        const identical = await this.areFilesIdentical(sourcePath, targetPath);
+        
+        if (identical) {
+          results.identical.push({
+            source: pair.source,
+            target: pair.target
+          });
+        } else {
+          results.different.push({
+            source: pair.source,
+            target: pair.target
+          });
+        }
+      } catch (error) {
+        results.errors.push({
+          source: pair.source,
+          target: pair.target,
+          error: error.message
+        });
+      }
+    }
+    
+    return results;
+  }
+  
+  /**
+   * Get file change summary
+   * 
+   * @param {Object} comparisonResults - Results from compareFiles
+   * @returns {Object} Summary statistics
+   */
+  getSummary(comparisonResults) {
+    return {
+      total: comparisonResults.identical.length + 
+             comparisonResults.different.length + 
+             comparisonResults.newFiles.length,
+      identical: comparisonResults.identical.length,
+      different: comparisonResults.different.length,
+      newFiles: comparisonResults.newFiles.length,
+      errors: comparisonResults.errors.length,
+      needsUpdate: comparisonResults.different.length + comparisonResults.newFiles.length > 0
+    };
+  }
+  
+  /**
+   * Filter files that need update
+   * 
+   * @param {Object} comparisonResults - Results from compareFiles
+   * @returns {Array} Files that need to be updated
+   */
+  getFilesNeedingUpdate(comparisonResults) {
+    return [
+      ...comparisonResults.different.map(f => ({ ...f, action: 'update' })),
+      ...comparisonResults.newFiles.map(f => ({ ...f, action: 'create' }))
+    ];
+  }
+  
+  /**
+   * Check if steering files have changed
+   * 
+   * @param {string} projectRoot - Project root path
+   * @param {string} templateRoot - Template root path
+   * @returns {Promise<Object>} Steering files comparison
+   */
+  async compareSteeringFiles(projectRoot, templateRoot) {
+    const steeringFiles = [
+      '.kiro/steering/CORE_PRINCIPLES.md',
+      '.kiro/steering/ENVIRONMENT.md',
+      '.kiro/steering/CURRENT_CONTEXT.md',
+      '.kiro/steering/RULES_GUIDE.md',
+      '.kiro/specs/SPEC_WORKFLOW_GUIDE.md',
+      '.kiro/README.md'
+    ];
+    
+    const filePairs = steeringFiles.map(file => ({
+      source: path.join(templateRoot, file),
+      target: path.join(projectRoot, file)
+    }));
+    
+    return await this.compareFiles(filePairs, projectRoot);
+  }
+}
+
+module.exports = FileDiff;