kiro-spec-engine 1.4.3 → 1.5.2

package/lib/backup/selective-backup.js

@@ -0,0 +1,207 @@
+/**
+ * Selective Backup System
+ * 
+ * Creates targeted backups of specific files rather than entire directories.
+ * Used for conflict resolution during adoption to backup only files being overwritten.
+ */
+
+const path = require('path');
+const fs = require('fs').promises;
+const {
+  pathExists,
+  ensureDirectory,
+  safeCopy,
+  readJSON,
+  writeJSON
+} = require('../utils/fs-utils');
+
+/**
+ * SelectiveBackup class for creating targeted file backups
+ */
+class SelectiveBackup {
+  constructor() {
+    this.backupDir = '.kiro/backups';
+  }
+
+  /**
+   * Creates a backup of specific files before overwriting
+   * 
+   * @param {string} projectPath - Project root path
+   * @param {string[]} filePaths - Relative paths of files to backup (from .kiro/)
+   * @param {Object} options - Backup options
+   * @param {string} options.type - Backup type (default: 'conflict')
+   * @returns {Promise<SelectiveBackupInfo>}
+   */
+  async createSelectiveBackup(projectPath, filePaths, options = {}) {
+    const { type = 'conflict' } = options;
+    
+    // Generate backup ID with timestamp
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').split('T');
+    const dateStr = timestamp[0];
+    const timeStr = timestamp[1].split('-').slice(0, 3).join('');
+    const backupId = `${type}-${dateStr}-${timeStr}`;
+    
+    const backupPath = path.join(projectPath, this.backupDir, backupId);
+    const filesBackupPath = path.join(backupPath, 'files');
+    
+    // Create backup directory structure
+    await ensureDirectory(backupPath);
+    await ensureDirectory(filesBackupPath);
+    
+    const backedUpFiles = [];
+    let totalSize = 0;
+    
+    // Backup each file
+    for (const filePath of filePaths) {
+      const sourcePath = path.join(projectPath, this.backupDir.replace('/backups', ''), filePath);
+      const destPath = path.join(filesBackupPath, filePath);
+      
+      // Check if source file exists
+      const sourceExists = await pathExists(sourcePath);
+      if (!sourceExists) {
+        continue; // Skip non-existent files
+      }
+      
+      // Ensure destination directory exists
+      const destDir = path.dirname(destPath);
+      await ensureDirectory(destDir);
+      
+      // Copy file
+      await safeCopy(sourcePath, destPath, { overwrite: true });
+      
+      // Get file size
+      const stats = await fs.stat(sourcePath);
+      totalSize += stats.size;
+      
+      backedUpFiles.push(filePath);
+    }
+    
+    // Create metadata
+    const metadata = {
+      id: backupId,
+      type,
+      created: new Date().toISOString(),
+      files: backedUpFiles,
+      fileCount: backedUpFiles.length,
+      totalSize
+    };
+    
+    // Write metadata
+    await writeJSON(path.join(backupPath, 'metadata.json'), metadata);
+    
+    // Write files list
+    await writeJSON(path.join(backupPath, 'files.json'), backedUpFiles);
+    
+    return {
+      id: backupId,
+      type,
+      created: metadata.created,
+      files: backedUpFiles,
+      fileCount: backedUpFiles.length,
+      totalSize,
+      path: backupPath
+    };
+  }
+
+  /**
+   * Restores specific files from a selective backup
+   * 
+   * @param {string} projectPath - Project root path
+   * @param {string} backupId - Backup ID to restore from
+   * @param {string[]} filePaths - Optional: specific files to restore (if not provided, restores all)
+   * @returns {Promise<RestoreResult>}
+   */
+  async restoreSelective(projectPath, backupId, filePaths = null) {
+    const backupPath = path.join(projectPath, this.backupDir, backupId);
+    
+    // Check if backup exists
+    const backupExists = await pathExists(backupPath);
+    if (!backupExists) {
+      throw new Error(`Backup not found: ${backupId}`);
+    }
+    
+    // Read metadata
+    const metadataPath = path.join(backupPath, 'metadata.json');
+    const metadata = await readJSON(metadataPath);
+    
+    if (!metadata) {
+      throw new Error(`Invalid backup: metadata.json not found in ${backupId}`);
+    }
+    
+    // Determine which files to restore
+    const filesToRestore = filePaths || metadata.files;
+    
+    const restoredFiles = [];
+    const errors = [];
+    
+    // Restore each file
+    for (const filePath of filesToRestore) {
+      try {
+        const sourcePath = path.join(backupPath, 'files', filePath);
+        const destPath = path.join(projectPath, this.backupDir.replace('/backups', ''), filePath);
+        
+        // Check if backup file exists
+        const sourceExists = await pathExists(sourcePath);
+        if (!sourceExists) {
+          errors.push(`File not found in backup: ${filePath}`);
+          continue;
+        }
+        
+        // Ensure destination directory exists
+        const destDir = path.dirname(destPath);
+        await ensureDirectory(destDir);
+        
+        // Restore file
+        await safeCopy(sourcePath, destPath, { overwrite: true });
+        restoredFiles.push(filePath);
+      } catch (error) {
+        errors.push(`Failed to restore ${filePath}: ${error.message}`);
+      }
+    }
+    
+    return {
+      success: errors.length === 0,
+      backupId,
+      restoredFiles,
+      errors
+    };
+  }
+
+  /**
+   * Lists files in a selective backup
+   * 
+   * @param {string} projectPath - Project root path
+   * @param {string} backupId - Backup ID
+   * @returns {Promise<string[]>} - Array of file paths in backup
+   */
+  async listBackupFiles(projectPath, backupId) {
+    const backupPath = path.join(projectPath, this.backupDir, backupId);
+    
+    // Check if backup exists
+    const backupExists = await pathExists(backupPath);
+    if (!backupExists) {
+      throw new Error(`Backup not found: ${backupId}`);
+    }
+    
+    // Read files list
+    const filesPath = path.join(backupPath, 'files.json');
+    const filesExists = await pathExists(filesPath);
+    
+    if (filesExists) {
+      const files = await readJSON(filesPath);
+      return files || [];
+    }
+    
+    // Fallback: read from metadata
+    const metadataPath = path.join(backupPath, 'metadata.json');
+    const metadata = await readJSON(metadataPath);
+    
+    if (metadata && metadata.files) {
+      return metadata.files;
+    }
+    
+    return [];
+  }
+}
+
+module.exports = SelectiveBackup;

package/lib/commands/adopt.js

@@ -15,6 +15,8 @@ const VersionManager = require('../version/version-manager');
 const SteeringManager = require('../steering/steering-manager');
 const AdoptionConfig = require('../steering/adoption-config');
 const { detectTool, generateAutoConfig } = require('../utils/tool-detector');
+const ConflictResolver = require('../adoption/conflict-resolver');
+const SelectiveBackup = require('../backup/selective-backup');
 
 /**
  * Executes the adopt command
@@ -23,10 +25,11 @@ const { detectTool, generateAutoConfig } = require('../utils/tool-detector');
  * @param {boolean} options.auto - Skip confirmations
  * @param {boolean} options.dryRun - Show what would change without making changes
  * @param {string} options.mode - Force specific adoption mode (fresh/partial/full)
+ * @param {boolean} options.force - Force overwrite conflicting files (creates backup first)
  * @returns {Promise<void>}
  */
 async function adoptCommand(options = {}) {
-  const { auto = false, dryRun = false, mode: forcedMode = null } = options;
+  const { auto = false, dryRun = false, mode: forcedMode = null, force = false } = options;
   const projectPath = process.cwd();
   
   console.log(chalk.red('🔥') + ' Kiro Spec Engine - Project Adoption');
@@ -71,14 +74,23 @@ async function adoptCommand(options = {}) {
       console.log('    - Create backup before changes');
     }
     
-    // Show conflicts if any
+    // Show conflicts if any (brief summary)
     if (detection.conflicts.length > 0) {
       console.log();
       console.log(chalk.yellow('⚠️  Conflicts detected:'));
       detection.conflicts.forEach(conflict => {
         console.log(`    - ${conflict.path}`);
       });
-      console.log('  Existing files will be preserved, template files will be skipped');
+      console.log();
+      
+      if (force) {
+        console.log(chalk.red('  ⚠️  --force enabled: Conflicting files will be overwritten'));
+        console.log(chalk.gray('  A backup will be created before overwriting'));
+      } else if (auto) {
+        console.log(chalk.gray('  --auto mode: Existing files will be preserved'));
+      } else {
+        console.log(chalk.gray('  You will be prompted to choose how to handle conflicts'));
+      }
     }
     
     console.log();
@@ -94,7 +106,8 @@ async function adoptCommand(options = {}) {
       
       const result = await adoptionStrategy.execute(projectPath, strategy, {
         kseVersion: packageJson.version,
-        dryRun: true
+        dryRun: true,
+        force
       });
       
       if (result.success) {
@@ -137,7 +150,71 @@ async function adoptCommand(options = {}) {
     
     console.log();
     
-    // 7. Handle steering strategy if conflicts detected
+    // 7. Handle conflicts interactively
+    let resolutionMap = {};
+    let conflictBackupId = null;
+    
+    if (detection.conflicts.length > 0) {
+      if (!auto && !force) {
+        // Interactive mode: prompt user for conflict resolution
+        const resolver = new ConflictResolver();
+        
+        // Show detailed conflict summary
+        resolver.displayConflictSummary(detection.conflicts);
+        
+        // Get resolution strategy
+        const conflictStrategy = await resolver.promptStrategy(detection.conflicts);
+        
+        // Resolve conflicts
+        resolutionMap = await resolver.resolveConflicts(detection.conflicts, conflictStrategy, projectPath);
+        
+        // Create selective backup if any files will be overwritten
+        const filesToOverwrite = Object.entries(resolutionMap)
+          .filter(([_, resolution]) => resolution === 'overwrite')
+          .map(([filePath, _]) => filePath);
+        
+        if (filesToOverwrite.length > 0) {
+          console.log();
+          console.log(chalk.blue('📦 Creating backup of files to be overwritten...'));
+          const selectiveBackup = new SelectiveBackup();
+          const backup = await selectiveBackup.createSelectiveBackup(
+            projectPath,
+            filesToOverwrite,
+            { type: 'conflict' }
+          );
+          conflictBackupId = backup.id;
+          console.log(chalk.green(`✅ Backup created: ${conflictBackupId}`));
+        }
+      } else if (force) {
+        // Force mode: overwrite all with backup
+        console.log();
+        console.log(chalk.blue('📦 Creating backup of conflicting files...'));
+        const filesToOverwrite = detection.conflicts.map(c => c.path);
+        const selectiveBackup = new SelectiveBackup();
+        const backup = await selectiveBackup.createSelectiveBackup(
+          projectPath,
+          filesToOverwrite,
+          { type: 'conflict' }
+        );
+        conflictBackupId = backup.id;
+        console.log(chalk.green(`✅ Backup created: ${conflictBackupId}`));
+        
+        resolutionMap = detection.conflicts.reduce((map, conflict) => {
+          map[conflict.path] = 'overwrite';
+          return map;
+        }, {});
+      } else if (auto) {
+        // Auto mode: skip all conflicts
+        resolutionMap = detection.conflicts.reduce((map, conflict) => {
+          map[conflict.path] = 'keep';
+          return map;
+        }, {});
+      }
+    }
+    
+    console.log();
+    
+    // 8. Handle steering strategy if conflicts detected
     let steeringStrategy = null;
     let steeringBackupId = null;
     
@@ -184,7 +261,7 @@ async function adoptCommand(options = {}) {
       console.log();
     }
     
-    // 8. Create backup if needed
+    // 9. Create backup if needed (for non-conflict scenarios)
     let backupId = null;
     if (detection.hasKiroDir && (strategy === 'partial' || strategy === 'full')) {
       console.log(chalk.blue('📦 Creating backup...'));
@@ -203,7 +280,7 @@ async function adoptCommand(options = {}) {
     
     console.log();
     
-    // 9. Execute adoption
+    // 10. Execute adoption
     console.log(chalk.blue('🚀 Executing adoption...'));
     const adoptionStrategy = getAdoptionStrategy(strategy);
     const packageJson = require('../../package.json');
@@ -211,12 +288,14 @@ async function adoptCommand(options = {}) {
     const result = await adoptionStrategy.execute(projectPath, strategy, {
       kseVersion: packageJson.version,
       dryRun: false,
-      backupId
+      backupId,
+      force,
+      resolutionMap // Pass resolution map to adoption strategy
     });
     
     console.log();
     
-    // 10. Report results
+    // 11. Report results
     if (result.success) {
       console.log(chalk.green('✅ Adoption completed successfully!'));
       console.log();
@@ -244,6 +323,12 @@ async function adoptCommand(options = {}) {
         result.filesSkipped.forEach(file => console.log(`  - ${file}`));
       }
       
+      if (conflictBackupId) {
+        console.log();
+        console.log(chalk.blue('📦 Conflict Backup:'), conflictBackupId);
+        console.log(chalk.gray('  Run'), chalk.cyan('kse rollback'), chalk.gray('to restore overwritten files'));
+      }
+      
       if (result.warnings.length > 0) {
         console.log();
         console.log(chalk.yellow('⚠️  Warnings:'));
@@ -258,7 +343,7 @@ async function adoptCommand(options = {}) {
       
       console.log();
       
-      // 11. Detect tool and offer automation setup
+      // 12. Detect tool and offer automation setup
       console.log(chalk.blue('🔍 Detecting your development environment...'));
       try {
         const toolDetection = await detectTool(projectPath);