kiro-spec-engine 1.1.0 → 1.2.1

package/lib/commands/adopt.js

@@ -0,0 +1,231 @@
+/**
+ * Adopt Command
+ * 
+ * Intelligently adopts existing projects into kiro-spec-engine.
+ * Supports fresh, partial, and full adoption modes.
+ */
+
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const path = require('path');
+const DetectionEngine = require('../adoption/detection-engine');
+const { getAdoptionStrategy } = require('../adoption/adoption-strategy');
+const BackupSystem = require('../backup/backup-system');
+const VersionManager = require('../version/version-manager');
+
+/**
+ * Executes the adopt command
+ * 
+ * @param {Object} options - Command options
+ * @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)
+ * @returns {Promise<void>}
+ */
+async function adoptCommand(options = {}) {
+  const { auto = false, dryRun = false, mode: forcedMode = null } = options;
+  const projectPath = process.cwd();
+  
+  console.log(chalk.red('🔥') + ' Kiro Spec Engine - Project Adoption');
+  console.log();
+  
+  try {
+    // 1. Detect project structure
+    console.log(chalk.blue('📦 Analyzing project structure...'));
+    const detectionEngine = new DetectionEngine();
+    const detection = await detectionEngine.analyze(projectPath);
+    
+    // 2. Determine strategy
+    const strategy = forcedMode || detectionEngine.determineStrategy(detection);
+    
+    // 3. Show analysis to user
+    console.log();
+    console.log(detectionEngine.getSummary(detection));
+    console.log();
+    
+    // 4. Show adoption plan
+    console.log(chalk.blue('📋 Adoption Plan:'));
+    console.log(`  Mode: ${chalk.cyan(strategy)}`);
+    
+    if (strategy === 'fresh') {
+      console.log('  Actions:');
+      console.log('    - Create .kiro/ directory structure');
+      console.log('    - Copy template files (steering, tools, docs)');
+      console.log('    - Create version.json');
+    } else if (strategy === 'partial') {
+      console.log('  Actions:');
+      console.log('    - Preserve existing specs/ and steering/');
+      console.log('    - Add missing components');
+      console.log('    - Create/update version.json');
+      if (detection.hasKiroDir) {
+        console.log('    - Create backup before changes');
+      }
+    } else if (strategy === 'full') {
+      console.log('  Actions:');
+      console.log(`    - Upgrade from ${detection.existingVersion || 'unknown'} to current version`);
+      console.log('    - Update template files');
+      console.log('    - Preserve user content (specs/)');
+      console.log('    - Create backup before changes');
+    }
+    
+    // Show conflicts if any
+    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();
+    
+    // 5. Dry run mode
+    if (dryRun) {
+      console.log(chalk.yellow('🔍 Dry run mode - no changes will be made'));
+      console.log();
+      
+      const adoptionStrategy = getAdoptionStrategy(strategy);
+      const versionManager = new VersionManager();
+      const packageJson = require('../../package.json');
+      
+      const result = await adoptionStrategy.execute(projectPath, strategy, {
+        kseVersion: packageJson.version,
+        dryRun: true
+      });
+      
+      if (result.success) {
+        console.log(chalk.green('✅ Dry run completed successfully'));
+        console.log();
+        console.log('Files that would be created:');
+        result.filesCreated.forEach(file => console.log(`  + ${file}`));
+        if (result.filesUpdated.length > 0) {
+          console.log('Files that would be updated:');
+          result.filesUpdated.forEach(file => console.log(`  ~ ${file}`));
+        }
+        if (result.filesSkipped.length > 0) {
+          console.log('Files that would be skipped:');
+          result.filesSkipped.forEach(file => console.log(`  - ${file}`));
+        }
+      } else {
+        console.log(chalk.red('❌ Dry run failed'));
+        result.errors.forEach(error => console.log(`  ${error}`));
+      }
+      
+      return;
+    }
+    
+    // 6. Confirm with user (unless --auto)
+    if (!auto) {
+      const { confirmed } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'confirmed',
+          message: 'Proceed with adoption?',
+          default: true
+        }
+      ]);
+      
+      if (!confirmed) {
+        console.log(chalk.yellow('Adoption cancelled'));
+        return;
+      }
+    }
+    
+    console.log();
+    
+    // 7. Create backup if needed
+    let backupId = null;
+    if (detection.hasKiroDir && (strategy === 'partial' || strategy === 'full')) {
+      console.log(chalk.blue('📦 Creating backup...'));
+      const backupSystem = new BackupSystem();
+      
+      try {
+        const backup = await backupSystem.createBackup(projectPath, { type: 'adopt' });
+        backupId = backup.id;
+        console.log(chalk.green(`✅ Backup created: ${backupId}`));
+      } catch (error) {
+        console.log(chalk.red(`❌ Failed to create backup: ${error.message}`));
+        console.log(chalk.yellow('Aborting adoption for safety'));
+        return;
+      }
+    }
+    
+    console.log();
+    
+    // 8. Execute adoption
+    console.log(chalk.blue('🚀 Executing adoption...'));
+    const adoptionStrategy = getAdoptionStrategy(strategy);
+    const packageJson = require('../../package.json');
+    
+    const result = await adoptionStrategy.execute(projectPath, strategy, {
+      kseVersion: packageJson.version,
+      dryRun: false,
+      backupId
+    });
+    
+    console.log();
+    
+    // 9. Report results
+    if (result.success) {
+      console.log(chalk.green('✅ Adoption completed successfully!'));
+      console.log();
+      
+      if (result.filesCreated.length > 0) {
+        console.log(chalk.blue('Files created:'));
+        result.filesCreated.forEach(file => console.log(`  + ${file}`));
+      }
+      
+      if (result.filesUpdated.length > 0) {
+        console.log(chalk.blue('Files updated:'));
+        result.filesUpdated.forEach(file => console.log(`  ~ ${file}`));
+      }
+      
+      if (result.filesSkipped.length > 0) {
+        console.log(chalk.gray('Files skipped:'));
+        result.filesSkipped.forEach(file => console.log(`  - ${file}`));
+      }
+      
+      if (result.warnings.length > 0) {
+        console.log();
+        console.log(chalk.yellow('⚠️  Warnings:'));
+        result.warnings.forEach(warning => console.log(`  ${warning}`));
+      }
+      
+      if (backupId) {
+        console.log();
+        console.log(chalk.blue('📦 Backup:'), backupId);
+        console.log(chalk.gray('  Run'), chalk.cyan('kse rollback'), chalk.gray('if you need to undo changes'));
+      }
+      
+      console.log();
+      console.log(chalk.blue('💡 Next steps:'));
+      console.log('  1. Review the .kiro/ directory structure');
+      console.log('  2. Create your first spec: ' + chalk.cyan('kse create-spec my-feature'));
+      console.log('  3. Check project status: ' + chalk.cyan('kse status'));
+      console.log();
+      console.log(chalk.red('🔥') + ' Ready to build with Kiro Spec Engine!');
+    } else {
+      console.log(chalk.red('❌ Adoption failed'));
+      console.log();
+      result.errors.forEach(error => console.log(chalk.red(`  ${error}`)));
+      
+      if (backupId) {
+        console.log();
+        console.log(chalk.blue('📦 Backup available:'), backupId);
+        console.log(chalk.gray('  Run'), chalk.cyan('kse rollback'), chalk.gray('to restore'));
+      }
+      
+      process.exit(1);
+    }
+  } catch (error) {
+    console.log();
+    console.log(chalk.red('❌ Error:'), error.message);
+    console.log();
+    console.log(chalk.gray('If you need help, please report this issue:'));
+    console.log(chalk.cyan('https://github.com/heguangyong/kiro-spec-engine/issues'));
+    process.exit(1);
+  }
+}
+
+module.exports = adoptCommand;

package/lib/commands/rollback.js

@@ -0,0 +1,219 @@
+/**
+ * Rollback Command
+ * 
+ * Restores project from a backup.
+ * Provides safety net for failed adoptions or upgrades.
+ */
+
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const BackupSystem = require('../backup/backup-system');
+
+/**
+ * Executes the rollback command
+ * 
+ * @param {Object} options - Command options
+ * @param {boolean} options.auto - Skip confirmations
+ * @param {string} options.backup - Specific backup ID to restore
+ * @returns {Promise<void>}
+ */
+async function rollbackCommand(options = {}) {
+  const { auto = false, backup: backupId = null } = options;
+  const projectPath = process.cwd();
+  
+  console.log(chalk.red('🔥') + ' Kiro Spec Engine - Rollback');
+  console.log();
+  
+  try {
+    const backupSystem = new BackupSystem();
+    
+    // 1. List available backups
+    console.log(chalk.blue('📦 Loading backups...'));
+    const backups = await backupSystem.listBackups(projectPath);
+    
+    if (backups.length === 0) {
+      console.log(chalk.yellow('⚠️  No backups found'));
+      console.log();
+      console.log(chalk.gray('Backups are created automatically during:'));
+      console.log('  - Project adoption (kse adopt)');
+      console.log('  - Version upgrades (kse upgrade)');
+      return;
+    }
+    
+    console.log();
+    console.log(chalk.blue('Available backups:'));
+    backups.forEach((backup, index) => {
+      const date = new Date(backup.created).toLocaleString();
+      const size = (backup.size / 1024).toFixed(1);
+      console.log(`  ${index + 1}. ${chalk.cyan(backup.id)}`);
+      console.log(`     Type: ${backup.type}`);
+      console.log(`     Version: ${backup.version}`);
+      console.log(`     Created: ${date}`);
+      console.log(`     Size: ${size} KB (${backup.files} files)`);
+      console.log();
+    });
+    
+    // 2. Select backup
+    let selectedBackup;
+    
+    if (backupId) {
+      // Use specified backup ID
+      selectedBackup = backups.find(b => b.id === backupId);
+      
+      if (!selectedBackup) {
+        console.log(chalk.red(`❌ Backup not found: ${backupId}`));
+        console.log();
+        console.log(chalk.gray('Available backups:'));
+        backups.forEach(b => console.log(`  - ${b.id}`));
+        return;
+      }
+    } else {
+      // Interactive selection
+      const { selection } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'selection',
+          message: 'Select backup to restore:',
+          choices: backups.map((backup, index) => ({
+            name: `${backup.id} (${backup.type}, ${new Date(backup.created).toLocaleString()})`,
+            value: index
+          }))
+        }
+      ]);
+      
+      selectedBackup = backups[selection];
+    }
+    
+    console.log();
+    console.log(chalk.blue('Selected backup:'));
+    console.log(`  ID: ${chalk.cyan(selectedBackup.id)}`);
+    console.log(`  Type: ${selectedBackup.type}`);
+    console.log(`  Version: ${selectedBackup.version}`);
+    console.log(`  Created: ${new Date(selectedBackup.created).toLocaleString()}`);
+    console.log();
+    
+    // 3. Validate backup
+    console.log(chalk.blue('🔍 Validating backup...'));
+    const isValid = await backupSystem.validateBackup(selectedBackup.path);
+    
+    if (!isValid) {
+      console.log(chalk.red('❌ Backup validation failed'));
+      console.log();
+      console.log(chalk.yellow('This backup may be corrupted or incomplete.'));
+      console.log(chalk.gray('Proceeding with restore may cause data loss.'));
+      
+      if (!auto) {
+        const { proceed } = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'proceed',
+            message: 'Proceed anyway? (not recommended)',
+            default: false
+          }
+        ]);
+        
+        if (!proceed) {
+          console.log(chalk.yellow('Rollback cancelled'));
+          return;
+        }
+      } else {
+        console.log(chalk.red('Aborting rollback (use --force to override)'));
+        return;
+      }
+    } else {
+      console.log(chalk.green('✅ Backup is valid'));
+    }
+    
+    console.log();
+    
+    // 4. Confirm with user (unless --auto)
+    if (!auto) {
+      console.log(chalk.yellow('⚠️  Warning: This will replace your current .kiro/ directory'));
+      console.log(chalk.gray('A backup of the current state will be created first'));
+      console.log();
+      
+      const { confirmed } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'confirmed',
+          message: `Restore from backup ${selectedBackup.id}?`,
+          default: false
+        }
+      ]);
+      
+      if (!confirmed) {
+        console.log(chalk.yellow('Rollback cancelled'));
+        return;
+      }
+    }
+    
+    console.log();
+    
+    // 5. Create backup of current state
+    console.log(chalk.blue('📦 Creating backup of current state...'));
+    
+    let currentBackup;
+    try {
+      currentBackup = await backupSystem.createBackup(projectPath, { type: 'pre-rollback' });
+      console.log(chalk.green(`✅ Current state backed up: ${currentBackup.id}`));
+    } catch (error) {
+      console.log(chalk.yellow(`⚠️  Could not create backup: ${error.message}`));
+      console.log(chalk.gray('Continuing with rollback...'));
+    }
+    
+    console.log();
+    
+    // 6. Restore from backup
+    console.log(chalk.blue('🔄 Restoring from backup...'));
+    
+    const result = await backupSystem.restore(projectPath, selectedBackup.id);
+    
+    console.log();
+    
+    // 7. Report results
+    if (result.success) {
+      console.log(chalk.green('✅ Rollback completed successfully!'));
+      console.log();
+      console.log(`  Restored ${result.filesRestored} files from backup`);
+      console.log(`  Backup: ${chalk.cyan(selectedBackup.id)}`);
+      
+      if (currentBackup) {
+        console.log();
+        console.log(chalk.blue('📦 Previous state backed up:'), currentBackup.id);
+        console.log(chalk.gray('  You can restore it if needed'));
+      }
+      
+      console.log();
+      console.log(chalk.blue('💡 Next steps:'));
+      console.log('  1. Verify your project is working correctly');
+      console.log('  2. Check project status: ' + chalk.cyan('kse status'));
+      console.log();
+      console.log(chalk.red('🔥') + ' Rollback complete!');
+    } else {
+      console.log(chalk.red('❌ Rollback failed'));
+      console.log();
+      console.log(chalk.red('This is a critical error. Your project may be in an inconsistent state.'));
+      
+      if (currentBackup) {
+        console.log();
+        console.log(chalk.blue('📦 Pre-rollback backup available:'), currentBackup.id);
+        console.log(chalk.gray('  You may be able to restore from this backup'));
+      }
+      
+      console.log();
+      console.log(chalk.gray('Please report this issue:'));
+      console.log(chalk.cyan('https://github.com/heguangyong/kiro-spec-engine/issues'));
+      
+      process.exit(1);
+    }
+  } catch (error) {
+    console.log();
+    console.log(chalk.red('❌ Error:'), error.message);
+    console.log();
+    console.log(chalk.gray('If you need help, please report this issue:'));
+    console.log(chalk.cyan('https://github.com/heguangyong/kiro-spec-engine/issues'));
+    process.exit(1);
+  }
+}
+
+module.exports = rollbackCommand;

package/lib/commands/upgrade.js

@@ -0,0 +1,231 @@
+/**
+ * Upgrade Command
+ * 
+ * Upgrades project to a newer version of kiro-spec-engine.
+ * Handles incremental upgrades and migration scripts.
+ */
+
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const path = require('path');
+const VersionManager = require('../version/version-manager');
+const MigrationEngine = require('../upgrade/migration-engine');
+const BackupSystem = require('../backup/backup-system');
+
+/**
+ * Executes the upgrade command
+ * 
+ * @param {Object} options - Command options
+ * @param {boolean} options.auto - Skip confirmations
+ * @param {boolean} options.dryRun - Show upgrade plan without making changes
+ * @param {string} options.to - Target version (default: current kse version)
+ * @returns {Promise<void>}
+ */
+async function upgradeCommand(options = {}) {
+  const { auto = false, dryRun = false, to: targetVersion = null } = options;
+  const projectPath = process.cwd();
+  
+  console.log(chalk.red('🔥') + ' Kiro Spec Engine - Project Upgrade');
+  console.log();
+  
+  try {
+    const versionManager = new VersionManager();
+    const migrationEngine = new MigrationEngine();
+    const packageJson = require('../../package.json');
+    
+    // 1. Read current version
+    console.log(chalk.blue('📦 Checking project version...'));
+    const currentVersionInfo = await versionManager.readVersion(projectPath);
+    
+    if (!currentVersionInfo) {
+      console.log(chalk.red('❌ No version.json found'));
+      console.log();
+      console.log(chalk.yellow('This project may not be initialized with kse.'));
+      console.log(chalk.gray('Run'), chalk.cyan('kse adopt'), chalk.gray('to adopt this project first.'));
+      return;
+    }
+    
+    const currentVersion = currentVersionInfo['kse-version'];
+    const targetVer = targetVersion || packageJson.version;
+    
+    console.log(`  Current version: ${chalk.cyan(currentVersion)}`);
+    console.log(`  Target version: ${chalk.cyan(targetVer)}`);
+    console.log();
+    
+    // 2. Check if upgrade is needed
+    if (!versionManager.needsUpgrade(currentVersion, targetVer)) {
+      console.log(chalk.green(`✅ Already at version ${targetVer}`));
+      console.log(chalk.gray('No upgrade needed'));
+      return;
+    }
+    
+    // 3. Plan upgrade
+    console.log(chalk.blue('📋 Planning upgrade...'));
+    const plan = await migrationEngine.planUpgrade(currentVersion, targetVer);
+    
+    console.log();
+    console.log(chalk.blue('Upgrade Plan:'));
+    console.log(`  From: ${chalk.cyan(plan.fromVersion)}`);
+    console.log(`  To: ${chalk.cyan(plan.toVersion)}`);
+    console.log(`  Path: ${plan.path.map(v => chalk.cyan(v)).join(' → ')}`);
+    console.log(`  Estimated time: ${plan.estimatedTime}`);
+    
+    if (plan.migrations.length > 0) {
+      console.log();
+      console.log(chalk.blue('Migrations:'));
+      plan.migrations.forEach((migration, index) => {
+        const icon = migration.breaking ? chalk.red('⚠️ ') : chalk.green('✅');
+        const label = migration.breaking ? chalk.red('BREAKING') : chalk.green('safe');
+        console.log(`  ${index + 1}. ${migration.from} → ${migration.to} [${label}]`);
+        if (migration.script) {
+          console.log(`     Script: ${chalk.gray(path.basename(migration.script))}`);
+        } else {
+          console.log(`     ${chalk.gray('No migration script needed')}`);
+        }
+      });
+    } else {
+      console.log();
+      console.log(chalk.gray('No migrations needed'));
+    }
+    
+    console.log();
+    
+    // 4. Dry run mode
+    if (dryRun) {
+      console.log(chalk.yellow('🔍 Dry run mode - no changes will be made'));
+      console.log();
+      
+      const result = await migrationEngine.executeUpgrade(projectPath, plan, {
+        dryRun: true
+      });
+      
+      if (result.success) {
+        console.log(chalk.green('✅ Dry run completed successfully'));
+        console.log();
+        console.log('Migrations that would be executed:');
+        result.migrationsExecuted.forEach((migration, index) => {
+          console.log(`  ${index + 1}. ${migration.from} → ${migration.to}`);
+          migration.changes.forEach(change => {
+            console.log(`     - ${change}`);
+          });
+        });
+      } else {
+        console.log(chalk.red('❌ Dry run failed'));
+        result.errors.forEach(error => console.log(`  ${error}`));
+      }
+      
+      return;
+    }
+    
+    // 5. Confirm with user (unless --auto)
+    if (!auto) {
+      const { confirmed } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'confirmed',
+          message: 'Proceed with upgrade?',
+          default: true
+        }
+      ]);
+      
+      if (!confirmed) {
+        console.log(chalk.yellow('Upgrade cancelled'));
+        return;
+      }
+    }
+    
+    console.log();
+    
+    // 6. Create backup
+    console.log(chalk.blue('📦 Creating backup...'));
+    const backupSystem = new BackupSystem();
+    
+    let backup;
+    try {
+      backup = await backupSystem.createBackup(projectPath, { type: 'upgrade' });
+      console.log(chalk.green(`✅ Backup created: ${backup.id}`));
+    } catch (error) {
+      console.log(chalk.red(`❌ Failed to create backup: ${error.message}`));
+      console.log(chalk.yellow('Aborting upgrade for safety'));
+      return;
+    }
+    
+    console.log();
+    
+    // 7. Execute upgrade
+    console.log(chalk.blue('🚀 Executing upgrade...'));
+    
+    const result = await migrationEngine.executeUpgrade(projectPath, plan, {
+      dryRun: false,
+      onProgress: (step, total, message) => {
+        console.log(`  [${step}/${total}] ${message}`);
+      }
+    });
+    
+    console.log();
+    
+    // 8. Validate
+    console.log(chalk.blue('🔍 Validating upgrade...'));
+    const validation = await migrationEngine.validate(projectPath);
+    
+    if (!validation.success) {
+      console.log(chalk.yellow('⚠️  Validation warnings:'));
+      validation.warnings.forEach(warning => console.log(`  ${warning}`));
+    }
+    
+    console.log();
+    
+    // 9. Report results
+    if (result.success) {
+      console.log(chalk.green('✅ Upgrade completed successfully!'));
+      console.log();
+      console.log(`  Upgraded from ${chalk.cyan(result.fromVersion)} to ${chalk.cyan(result.toVersion)}`);
+      
+      if (result.migrationsExecuted.length > 0) {
+        console.log();
+        console.log(chalk.blue('Migrations executed:'));
+        result.migrationsExecuted.forEach((migration, index) => {
+          const icon = migration.success ? chalk.green('✅') : chalk.red('❌');
+          console.log(`  ${icon} ${migration.from} → ${migration.to}`);
+          if (migration.changes.length > 0) {
+            migration.changes.forEach(change => {
+              console.log(`     - ${change}`);
+            });
+          }
+        });
+      }
+      
+      if (result.warnings.length > 0) {
+        console.log();
+        console.log(chalk.yellow('⚠️  Warnings:'));
+        result.warnings.forEach(warning => console.log(`  ${warning}`));
+      }
+      
+      console.log();
+      console.log(chalk.blue('📦 Backup:'), backup.id);
+      console.log(chalk.gray('  Run'), chalk.cyan('kse rollback'), chalk.gray('if you encounter issues'));
+      
+      console.log();
+      console.log(chalk.red('🔥') + ' Upgrade complete!');
+    } else {
+      console.log(chalk.red('❌ Upgrade failed'));
+      console.log();
+      result.errors.forEach(error => console.log(chalk.red(`  ${error}`)));
+      
+      console.log();
+      console.log(chalk.blue('📦 Backup available:'), backup.id);
+      console.log(chalk.gray('  Run'), chalk.cyan('kse rollback'), chalk.gray('to restore'));
+      
+      process.exit(1);
+    }
+  } catch (error) {
+    console.log();
+    console.log(chalk.red('❌ Error:'), error.message);
+    console.log();
+    console.log(chalk.gray('If you need help, please report this issue:'));
+    console.log(chalk.cyan('https://github.com/heguangyong/kiro-spec-engine/issues'));
+    process.exit(1);
+  }
+}
+
+module.exports = upgradeCommand;