kiro-spec-engine 1.0.0 → 1.2.0

package/lib/adoption/detection-engine.js

@@ -0,0 +1,242 @@
+/**
+ * Detection Engine
+ * 
+ * Analyzes project structure and determines the appropriate adoption strategy.
+ * Detects project type, existing .kiro/ components, and potential conflicts.
+ */
+
+const path = require('path');
+const {
+  pathExists,
+  listFiles,
+  readJSON
+} = require('../utils/fs-utils');
+
+class DetectionEngine {
+  constructor() {
+    this.kiroDir = '.kiro';
+    this.versionFile = 'version.json';
+    this.specsDir = 'specs';
+    this.steeringDir = 'steering';
+    this.toolsDir = 'tools';
+  }
+
+  /**
+   * Analyzes project directory and returns detection result
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {Promise<DetectionResult>}
+   */
+  async analyze(projectPath) {
+    try {
+      const kiroPath = path.join(projectPath, this.kiroDir);
+      const hasKiroDir = await pathExists(kiroPath);
+      
+      let hasVersionFile = false;
+      let hasSpecs = false;
+      let hasSteering = false;
+      let hasTools = false;
+      let existingVersion = null;
+      
+      if (hasKiroDir) {
+        // Check for version.json
+        const versionPath = path.join(kiroPath, this.versionFile);
+        hasVersionFile = await pathExists(versionPath);
+        
+        if (hasVersionFile) {
+          try {
+            const versionInfo = await readJSON(versionPath);
+            existingVersion = versionInfo['kse-version'] || null;
+          } catch (error) {
+            // Invalid version file
+            hasVersionFile = false;
+          }
+        }
+        
+        // Check for specs/
+        const specsPath = path.join(kiroPath, this.specsDir);
+        hasSpecs = await pathExists(specsPath);
+        
+        // Check for steering/
+        const steeringPath = path.join(kiroPath, this.steeringDir);
+        hasSteering = await pathExists(steeringPath);
+        
+        // Check for tools/
+        const toolsPath = path.join(kiroPath, this.toolsDir);
+        hasTools = await pathExists(toolsPath);
+      }
+      
+      // Detect project type
+      const projectType = await this.detectProjectType(projectPath);
+      
+      // Detect conflicts (only if we're going to add template files)
+      const conflicts = hasKiroDir ? await this.detectConflicts(projectPath) : [];
+      
+      return {
+        hasKiroDir,
+        hasVersionFile,
+        hasSpecs,
+        hasSteering,
+        hasTools,
+        projectType,
+        existingVersion,
+        conflicts
+      };
+    } catch (error) {
+      throw new Error(`Failed to analyze project: ${error.message}`);
+    }
+  }
+
+  /**
+   * Determines which adoption strategy to use
+   * 
+   * @param {DetectionResult} result - Detection result from analyze()
+   * @returns {AdoptionMode} - 'fresh', 'partial', or 'full'
+   */
+  determineStrategy(result) {
+    // Fresh adoption: no .kiro/ directory
+    if (!result.hasKiroDir) {
+      return 'fresh';
+    }
+    
+    // Partial adoption: .kiro/ exists but no version.json
+    if (!result.hasVersionFile) {
+      return 'partial';
+    }
+    
+    // Full adoption: complete .kiro/ with version.json
+    return 'full';
+  }
+
+  /**
+   * Detects project type (Node.js, Python, mixed, unknown)
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {Promise<ProjectType>}
+   */
+  async detectProjectType(projectPath) {
+    try {
+      const hasPackageJson = await pathExists(path.join(projectPath, 'package.json'));
+      const hasRequirementsTxt = await pathExists(path.join(projectPath, 'requirements.txt'));
+      const hasPyprojectToml = await pathExists(path.join(projectPath, 'pyproject.toml'));
+      const hasSetupPy = await pathExists(path.join(projectPath, 'setup.py'));
+      
+      const isNodeJs = hasPackageJson;
+      const isPython = hasRequirementsTxt || hasPyprojectToml || hasSetupPy;
+      
+      if (isNodeJs && isPython) {
+        return 'mixed';
+      } else if (isNodeJs) {
+        return 'nodejs';
+      } else if (isPython) {
+        return 'python';
+      } else {
+        return 'unknown';
+      }
+    } catch (error) {
+      throw new Error(`Failed to detect project type: ${error.message}`);
+    }
+  }
+
+  /**
+   * Detects conflicts between existing files and template files
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {Promise<FileConflict[]>}
+   */
+  async detectConflicts(projectPath) {
+    const conflicts = [];
+    
+    try {
+      const kiroPath = path.join(projectPath, this.kiroDir);
+      
+      // Define template files that might conflict
+      const templateFiles = [
+        'steering/CORE_PRINCIPLES.md',
+        'steering/ENVIRONMENT.md',
+        'steering/CURRENT_CONTEXT.md',
+        'steering/RULES_GUIDE.md',
+        'tools/ultrawork_enhancer.py',
+        'README.md',
+        'ultrawork-application-guide.md',
+        'ultrawork-integration-summary.md',
+        'sisyphus-deep-dive.md'
+      ];
+      
+      for (const templateFile of templateFiles) {
+        const filePath = path.join(kiroPath, templateFile);
+        const exists = await pathExists(filePath);
+        
+        if (exists) {
+          conflicts.push({
+            path: templateFile,
+            type: 'file',
+            existingContent: filePath,
+            templateContent: `template:${templateFile}`
+          });
+        }
+      }
+      
+      return conflicts;
+    } catch (error) {
+      throw new Error(`Failed to detect conflicts: ${error.message}`);
+    }
+  }
+
+  /**
+   * Validates that a project path is valid
+   * 
+   * @param {string} projectPath - Path to validate
+   * @returns {Promise<boolean>}
+   */
+  async validateProjectPath(projectPath) {
+    try {
+      const exists = await pathExists(projectPath);
+      if (!exists) {
+        return false;
+      }
+      
+      // Check if it's a directory
+      const fs = require('fs-extra');
+      const stats = await fs.stat(projectPath);
+      return stats.isDirectory();
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Gets a summary of the detection result for display
+   * 
+   * @param {DetectionResult} result - Detection result
+   * @returns {string} - Human-readable summary
+   */
+  getSummary(result) {
+    const lines = [];
+    
+    lines.push('Project Analysis:');
+    lines.push(`  Project Type: ${result.projectType}`);
+    lines.push(`  .kiro/ Directory: ${result.hasKiroDir ? 'Yes' : 'No'}`);
+    
+    if (result.hasKiroDir) {
+      lines.push(`  version.json: ${result.hasVersionFile ? 'Yes' : 'No'}`);
+      if (result.existingVersion) {
+        lines.push(`  Current Version: ${result.existingVersion}`);
+      }
+      lines.push(`  specs/: ${result.hasSpecs ? 'Yes' : 'No'}`);
+      lines.push(`  steering/: ${result.hasSteering ? 'Yes' : 'No'}`);
+      lines.push(`  tools/: ${result.hasTools ? 'Yes' : 'No'}`);
+      
+      if (result.conflicts.length > 0) {
+        lines.push(`  Conflicts: ${result.conflicts.length} file(s)`);
+      }
+    }
+    
+    const strategy = this.determineStrategy(result);
+    lines.push(`  Recommended Strategy: ${strategy}`);
+    
+    return lines.join('\n');
+  }
+}
+
+module.exports = DetectionEngine;

package/lib/backup/backup-system.js

@@ -0,0 +1,372 @@
+/**
+ * Backup System
+ * 
+ * Creates, manages, and restores backups of the .kiro/ directory.
+ * Provides rollback capability for safe adoption and upgrade operations.
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+const {
+  pathExists,
+  copyDirectory,
+  ensureDirectory,
+  listFiles,
+  listFilesRecursive,
+  getDirectorySize,
+  readJSON,
+  writeJSON,
+  remove
+} = require('../utils/fs-utils');
+
+class BackupSystem {
+  constructor() {
+    this.backupDirName = 'backups';
+  }
+
+  /**
+   * Gets the path to the backups directory
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {string} - Absolute path to backups directory
+   */
+  getBackupDir(projectPath) {
+    return path.join(projectPath, '.kiro', this.backupDirName);
+  }
+
+  /**
+   * Gets the path to the .kiro directory
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {string} - Absolute path to .kiro directory
+   */
+  getKiroDir(projectPath) {
+    return path.join(projectPath, '.kiro');
+  }
+
+  /**
+   * Generates a backup ID based on type and timestamp
+   * 
+   * @param {string} type - Backup type (adopt, upgrade, pre-rollback)
+   * @returns {string} - Backup ID (e.g., "adopt-2026-01-23-100000")
+   */
+  generateBackupId(type) {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    const hours = String(now.getHours()).padStart(2, '0');
+    const minutes = String(now.getMinutes()).padStart(2, '0');
+    const seconds = String(now.getSeconds()).padStart(2, '0');
+    
+    return `${type}-${year}-${month}-${day}-${hours}${minutes}${seconds}`;
+  }
+
+  /**
+   * Creates backup of .kiro/ directory
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @param {Object} options - Backup options
+   * @param {string} options.type - Backup type (adopt, upgrade, pre-rollback)
+   * @returns {Promise<BackupInfo>}
+   */
+  async createBackup(projectPath, options = {}) {
+    const { type = 'manual' } = options;
+    
+    try {
+      const kiroDir = this.getKiroDir(projectPath);
+      
+      // Check if .kiro/ exists
+      const kiroExists = await pathExists(kiroDir);
+      if (!kiroExists) {
+        throw new Error('.kiro/ directory does not exist');
+      }
+      
+      // Create backups directory if it doesn't exist
+      const backupDir = this.getBackupDir(projectPath);
+      await ensureDirectory(backupDir);
+      
+      // Generate backup ID
+      const backupId = this.generateBackupId(type);
+      const backupPath = path.join(backupDir, backupId);
+      
+      // Check if backup already exists (shouldn't happen with timestamp)
+      const backupExists = await pathExists(backupPath);
+      if (backupExists) {
+        throw new Error(`Backup already exists: ${backupId}`);
+      }
+      
+      // Create backup directory
+      await ensureDirectory(backupPath);
+      
+      // Copy .kiro/ contents to backup (excluding backups/ itself)
+      const items = await listFiles(kiroDir);
+      
+      for (const item of items) {
+        // Skip the backups directory itself
+        if (item === this.backupDirName) {
+          continue;
+        }
+        
+        const sourcePath = path.join(kiroDir, item);
+        const destPath = path.join(backupPath, item);
+        
+        await copyDirectory(sourcePath, destPath, { overwrite: false });
+      }
+      
+      // Get backup metadata
+      const files = await listFilesRecursive(backupPath);
+      const size = await getDirectorySize(backupPath);
+      
+      // Read version from backup if it exists
+      const versionPath = path.join(backupPath, 'version.json');
+      let version = 'unknown';
+      try {
+        const versionExists = await pathExists(versionPath);
+        if (versionExists) {
+          const versionInfo = await readJSON(versionPath);
+          version = versionInfo['kse-version'] || 'unknown';
+        }
+      } catch (error) {
+        // Ignore version read errors
+      }
+      
+      // Create metadata file
+      const metadata = {
+        id: backupId,
+        type,
+        created: new Date().toISOString(),
+        version,
+        size,
+        files: files.length
+      };
+      
+      const metadataPath = path.join(backupPath, 'metadata.json');
+      await writeJSON(metadataPath, metadata, { spaces: 2 });
+      
+      // Return backup info
+      return {
+        id: backupId,
+        type,
+        created: metadata.created,
+        version,
+        size,
+        files: files.length,
+        path: backupPath
+      };
+    } catch (error) {
+      throw new Error(`Failed to create backup: ${error.message}`);
+    }
+  }
+
+  /**
+   * Lists available backups
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {Promise<BackupInfo[]>} - Array of backup info, sorted by date (newest first)
+   */
+  async listBackups(projectPath) {
+    try {
+      const backupDir = this.getBackupDir(projectPath);
+      
+      // Check if backups directory exists
+      const backupDirExists = await pathExists(backupDir);
+      if (!backupDirExists) {
+        return [];
+      }
+      
+      // List backup directories
+      const items = await listFiles(backupDir);
+      const backups = [];
+      
+      for (const item of items) {
+        const backupPath = path.join(backupDir, item);
+        const metadataPath = path.join(backupPath, 'metadata.json');
+        
+        try {
+          // Check if metadata exists
+          const metadataExists = await pathExists(metadataPath);
+          if (!metadataExists) {
+            continue;
+          }
+          
+          // Read metadata
+          const metadata = await readJSON(metadataPath);
+          
+          backups.push({
+            id: metadata.id,
+            type: metadata.type,
+            created: metadata.created,
+            version: metadata.version,
+            size: metadata.size,
+            files: metadata.files,
+            path: backupPath
+          });
+        } catch (error) {
+          // Skip backups with invalid metadata
+          continue;
+        }
+      }
+      
+      // Sort by created date (newest first)
+      backups.sort((a, b) => {
+        return new Date(b.created) - new Date(a.created);
+      });
+      
+      return backups;
+    } catch (error) {
+      throw new Error(`Failed to list backups: ${error.message}`);
+    }
+  }
+
+  /**
+   * Restores from backup
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @param {string} backupId - Backup ID to restore from
+   * @returns {Promise<RestoreResult>}
+   */
+  async restore(projectPath, backupId) {
+    try {
+      const backupDir = this.getBackupDir(projectPath);
+      const backupPath = path.join(backupDir, backupId);
+      
+      // Check if backup exists
+      const backupExists = await pathExists(backupPath);
+      if (!backupExists) {
+        throw new Error(`Backup not found: ${backupId}`);
+      }
+      
+      // Validate backup before restoring
+      const isValid = await this.validateBackup(backupPath);
+      if (!isValid) {
+        throw new Error(`Backup validation failed: ${backupId}`);
+      }
+      
+      const kiroDir = this.getKiroDir(projectPath);
+      
+      // Get list of items to restore (excluding metadata.json)
+      const items = await listFiles(backupPath);
+      const itemsToRestore = items.filter(item => item !== 'metadata.json');
+      
+      // Remove existing .kiro/ contents (except backups/)
+      const existingItems = await listFiles(kiroDir);
+      for (const item of existingItems) {
+        if (item === this.backupDirName) {
+          continue;
+        }
+        
+        const itemPath = path.join(kiroDir, item);
+        await remove(itemPath);
+      }
+      
+      // Restore items from backup
+      const restoredFiles = [];
+      for (const item of itemsToRestore) {
+        const sourcePath = path.join(backupPath, item);
+        const destPath = path.join(kiroDir, item);
+        
+        await copyDirectory(sourcePath, destPath, { overwrite: true });
+        restoredFiles.push(item);
+      }
+      
+      return {
+        success: true,
+        backupId,
+        filesRestored: restoredFiles.length,
+        files: restoredFiles
+      };
+    } catch (error) {
+      throw new Error(`Failed to restore backup: ${error.message}`);
+    }
+  }
+
+  /**
+   * Validates backup integrity
+   * 
+   * @param {string} backupPath - Absolute path to backup directory
+   * @returns {Promise<boolean>}
+   */
+  async validateBackup(backupPath) {
+    try {
+      // Check if backup directory exists
+      const backupExists = await pathExists(backupPath);
+      if (!backupExists) {
+        return false;
+      }
+      
+      // Check if metadata exists
+      const metadataPath = path.join(backupPath, 'metadata.json');
+      const metadataExists = await pathExists(metadataPath);
+      if (!metadataExists) {
+        return false;
+      }
+      
+      // Read and validate metadata
+      const metadata = await readJSON(metadataPath);
+      if (!metadata.id || !metadata.type || !metadata.created) {
+        return false;
+      }
+      
+      // Count files in backup
+      const files = await listFilesRecursive(backupPath);
+      // Subtract 1 for metadata.json itself
+      const fileCount = files.length - 1;
+      
+      // Verify file count matches metadata (allow some tolerance)
+      // Files might be slightly different due to metadata.json
+      if (Math.abs(fileCount - metadata.files) > 1) {
+        return false;
+      }
+      
+      // Verify version.json exists and is valid (if present)
+      const versionPath = path.join(backupPath, 'version.json');
+      const versionExists = await pathExists(versionPath);
+      if (versionExists) {
+        try {
+          const versionInfo = await readJSON(versionPath);
+          // Basic validation
+          if (!versionInfo['kse-version']) {
+            return false;
+          }
+        } catch (error) {
+          return false;
+        }
+      }
+      
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Cleans old backups (keeps last N backups)
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @param {number} keepCount - Number of backups to keep (default: 5)
+   * @returns {Promise<void>}
+   */
+  async cleanOldBackups(projectPath, keepCount = 5) {
+    try {
+      // Get all backups sorted by date (newest first)
+      const backups = await this.listBackups(projectPath);
+      
+      // If we have fewer backups than keepCount, nothing to do
+      if (backups.length <= keepCount) {
+        return;
+      }
+      
+      // Remove old backups
+      const backupsToRemove = backups.slice(keepCount);
+      
+      for (const backup of backupsToRemove) {
+        await remove(backup.path);
+      }
+    } catch (error) {
+      throw new Error(`Failed to clean old backups: ${error.message}`);
+    }
+  }
+}
+
+module.exports = BackupSystem;