kiro-spec-engine 1.6.3 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,116 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.0] - 2026-01-24
+
+### Added - Interactive Conflict Resolution System 🎯
+
+**Spec 10-00**: Complete overhaul of `kse adopt` conflict handling with interactive resolution
+
+**Core Features**:
+- **Interactive Conflict Resolution**: Choose how to handle each conflicting file
+  - Three strategies: Skip all, Overwrite all, Review each file
+  - Per-file review with progress tracking ("Conflict 2 of 5")
+  - View file differences before deciding
+- **Selective Backup System**: Only backs up files being overwritten (not entire .kiro/)
+  - Efficient backup creation with conflict-specific IDs
+  - Selective restore capability
+  - Automatic backup before any overwrites
+- **File Difference Viewer**: Compare existing vs template files
+  - Side-by-side metadata comparison (size, modification date)
+  - Line-by-line diff for text files (with line limits)
+  - Binary file detection and handling
+  - Color-coded output with chalk
+
+**Enhanced Modes**:
+- **Force Mode** (`--force`): Automatically overwrite all conflicts with backup
+  - Clear warning message before proceeding
+  - Selective backup of all conflicting files
+  - No interactive prompts
+- **Auto Mode** (`--auto`): Non-interactive adoption
+  - Defaults to skip-all strategy (safe default)
+  - Can combine with `--force` for auto-overwrite
+  - Suitable for CI/CD environments
+- **Dry Run Mode** (`--dry-run`): Preview conflict actions
+  - Shows what conflicts would be detected
+  - Displays what action would be taken
+  - No file modifications or backups created
+
+**Improved Reporting**:
+- **Conflict Resolution Summary**: Detailed adoption results
+  - List of skipped files with reasons
+  - List of overwritten files
+  - Backup ID for rollback
+  - Total conflict count
+  - Rollback instructions when applicable
+- **Error Handling**: Comprehensive error recovery
+  - Backup failure detection and abort
+  - Individual file overwrite failure handling
+  - Diff generation failure graceful degradation
+  - Non-interactive environment detection
+  - Detailed error summaries with recovery guidance
+
+**New Components**:
+- `lib/adoption/conflict-resolver.js` - Interactive conflict resolution prompts
+- `lib/backup/selective-backup.js` - Selective file backup system
+- `lib/adoption/diff-viewer.js` - File difference viewer
+- Enhanced `lib/adoption/detection-engine.js` - Conflict categorization
+- Enhanced `lib/commands/adopt.js` - Integrated conflict resolution flow
+- Enhanced `lib/adoption/adoption-strategy.js` - Resolution map support
+
+**Usage Examples**:
+```bash
+# Interactive mode (default) - prompts for each conflict
+kse adopt
+
+# Force mode - overwrite all conflicts with backup
+kse adopt --force
+
+# Auto mode - skip all conflicts automatically
+kse adopt --auto
+
+# Auto + force - overwrite all conflicts without prompts
+kse adopt --auto --force
+
+# Dry run - preview what would happen
+kse adopt --dry-run
+```
+
+**Benefits**:
+- Full control over which files to keep or overwrite
+- View differences before making decisions
+- Efficient backups (only affected files, not entire .kiro/)
+- Safe adoption with automatic rollback support
+- Clear feedback about what changed
+- Suitable for both interactive and automated workflows
+
+**Technical Details**:
+- Uses inquirer for interactive prompts
+- Categorizes conflicts by type (steering, documentation, tools, other)
+- Preserves directory structure in selective backups
+- Handles both text and binary files appropriately
+- Cross-platform path handling (Windows/Unix)
+- Non-TTY environment detection for CI/CD
+
+## [1.6.4] - 2026-01-24
+
+### Added
+- **Prominent clarification to prevent confusion with Kiro IDE** 🎯
+  - Added warning box at top of README.md and README.zh.md
+  - Clarifies that kse is an npm package/CLI tool, NOT the Kiro IDE desktop application
+  - Updated package.json description to explicitly state the difference
+  - **Triggered by**: Real user feedback - iFlow (using GLM-4.7) confused kse with Kiro IDE and tried to download the wrong software
+
+**Why this matters:**
+- Prevents AI tools (especially smaller models) from confusing kse with Kiro IDE
+- Saves users time by immediately clarifying what kse is
+- Improves first-time user experience
+- Sets foundation for Spec 11 (comprehensive documentation alignment)
+
+**User feedback that triggered this:**
+> "iFlow 用 GLM-4.7 好傻 下载 kiro 了"  
+> (iFlow using GLM-4.7 was silly and downloaded Kiro [IDE] instead)
+
 ## [1.6.3] - 2026-01-24
 
 ### Fixed

package/README.md

@@ -3,6 +3,9 @@
 [![npm version](https://badge.fury.io/js/kiro-spec-engine.svg)](https://badge.fury.io/js/kiro-spec-engine)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+> **⚠️ Important Clarification**: `kiro-spec-engine` (kse) is an **npm package and CLI tool** for spec-driven development.  
+> It is **NOT** the Kiro IDE desktop application. If you're looking for Kiro IDE, visit https://kiro.dev
+
 **A context provider for AI coding tools** - Structure your project requirements, design, and tasks so AI assistants can help you build better software.
 
 English | [简体中文](README.zh.md)

package/README.zh.md

@@ -3,6 +3,9 @@
 [![npm version](https://badge.fury.io/js/kiro-spec-engine.svg)](https://badge.fury.io/js/kiro-spec-engine)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+> **⚠️ 重要说明**: `kiro-spec-engine` (kse) 是一个 **npm 包和 CLI 工具**，用于 Spec 驱动开发。  
+> 它**不是** Kiro IDE 桌面应用程序。如果你在寻找 Kiro IDE，请访问 https://kiro.dev
+
 **AI 编码工具的上下文提供者** - 结构化你的项目需求、设计和任务，让 AI 助手帮你构建更好的软件。
 
 [English](README.md) | 简体中文

package/lib/adoption/conflict-resolver.js

@@ -166,7 +166,18 @@ class ConflictResolver {
         const existingPath = path.join(projectPath, '.kiro', conflict.path);
         const templatePath = conflict.templatePath || path.join(projectPath, 'template', '.kiro', conflict.path);
         
-        await this.diffViewer.showDiff(existingPath, templatePath);
+        try {
+          await this.diffViewer.showDiff(existingPath, templatePath);
+        } catch (diffError) {
+          console.log();
+          console.log(chalk.yellow('⚠️  Unable to generate diff for this file'));
+          console.log(chalk.gray(`  Reason: ${diffError.message}`));
+          console.log();
+          console.log(chalk.gray('  You can open the files in your editor to compare:'));
+          console.log(chalk.gray(`    Existing: ${existingPath}`));
+          console.log(chalk.gray(`    Template: ${templatePath}`));
+          console.log();
+        }
         
         // Re-prompt with only keep/overwrite options
         const { finalAction } = await inquirer.prompt([

package/lib/adoption/detection-engine.js

@@ -187,6 +187,29 @@ class DetectionEngine {
     }
   }
 
+  /**
+   * Categorizes conflicts by type for better display
+   * 
+   * @param {FileConflict[]} conflicts - Array of conflicts
+   * @returns {CategorizedConflicts}
+   */
+  categorizeConflicts(conflicts) {
+    return {
+      steering: conflicts.filter(c => c.path.startsWith('steering/')),
+      documentation: conflicts.filter(c => 
+        c.path.endsWith('.md') && 
+        !c.path.startsWith('steering/') && 
+        !c.path.startsWith('tools/')
+      ),
+      tools: conflicts.filter(c => c.path.startsWith('tools/')),
+      other: conflicts.filter(c => 
+        !c.path.startsWith('steering/') && 
+        !c.path.startsWith('tools/') && 
+        !c.path.endsWith('.md')
+      )
+    };
+  }
+
   /**
    * Validates that a project path is valid
    * 

package/lib/commands/adopt.js

@@ -100,6 +100,45 @@ async function adoptCommand(options = {}) {
       console.log(chalk.yellow('🔍 Dry run mode - no changes will be made'));
       console.log();
       
+      // Show how conflicts would be handled
+      if (detection.conflicts.length > 0) {
+        console.log(chalk.blue('Conflict Resolution Preview:'));
+        console.log();
+        
+        if (force) {
+          console.log(chalk.yellow('  With --force flag:'));
+          console.log('    - All conflicting files would be overwritten');
+          console.log('    - Backup would be created before overwriting');
+          console.log();
+          console.log('  Files that would be overwritten:');
+          detection.conflicts.forEach(conflict => {
+            console.log(chalk.red(`    ~ ${conflict.path}`));
+          });
+        } else if (auto) {
+          console.log(chalk.gray('  With --auto flag:'));
+          console.log('    - All conflicting files would be preserved');
+          console.log('    - Template files would be skipped');
+          console.log();
+          console.log('  Files that would be skipped:');
+          detection.conflicts.forEach(conflict => {
+            console.log(chalk.gray(`    - ${conflict.path}`));
+          });
+        } else {
+          console.log(chalk.blue('  In interactive mode:'));
+          console.log('    - You would be prompted to choose:');
+          console.log('      • Skip all conflicting files');
+          console.log('      • Overwrite all (with backup)');
+          console.log('      • Review each conflict individually');
+          console.log();
+          console.log('  Conflicting files:');
+          detection.conflicts.forEach(conflict => {
+            console.log(chalk.yellow(`    ? ${conflict.path}`));
+          });
+        }
+        
+        console.log();
+      }
+      
       const adoptionStrategy = getAdoptionStrategy(strategy);
       const versionManager = new VersionManager();
       const packageJson = require('../../package.json');
@@ -177,6 +216,36 @@ async function adoptCommand(options = {}) {
           console.log();
           console.log(chalk.blue('📦 Creating backup of files to be overwritten...'));
           const selectiveBackup = new SelectiveBackup();
+          
+          try {
+            const backup = await selectiveBackup.createSelectiveBackup(
+              projectPath,
+              filesToOverwrite,
+              { type: 'conflict' }
+            );
+            conflictBackupId = backup.id;
+            console.log(chalk.green(`✅ Backup created: ${conflictBackupId}`));
+          } catch (backupError) {
+            console.log(chalk.red(`❌ Failed to create backup: ${backupError.message}`));
+            console.log();
+            console.log(chalk.yellow('⚠️  Aborting adoption for safety'));
+            console.log(chalk.gray('  Possible causes:'));
+            console.log(chalk.gray('    - Insufficient disk space'));
+            console.log(chalk.gray('    - Permission denied'));
+            console.log(chalk.gray('    - File system error'));
+            console.log();
+            console.log(chalk.gray('  Please resolve the issue and try again'));
+            process.exit(1);
+          }
+        }
+      } 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();
+        
+        try {
           const backup = await selectiveBackup.createSelectiveBackup(
             projectPath,
             filesToOverwrite,
@@ -184,20 +253,18 @@ async function adoptCommand(options = {}) {
           );
           conflictBackupId = backup.id;
           console.log(chalk.green(`✅ Backup created: ${conflictBackupId}`));
+        } catch (backupError) {
+          console.log(chalk.red(`❌ Failed to create backup: ${backupError.message}`));
+          console.log();
+          console.log(chalk.yellow('⚠️  Aborting adoption for safety'));
+          console.log(chalk.gray('  Cannot proceed with --force without a backup'));
+          console.log();
+          console.log(chalk.gray('  Possible solutions:'));
+          console.log(chalk.gray('    - Free up disk space'));
+          console.log(chalk.gray('    - Check file permissions'));
+          console.log(chalk.gray('    - Try without --force to skip conflicts'));
+          process.exit(1);
         }
-      } 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';
@@ -300,6 +367,43 @@ async function adoptCommand(options = {}) {
       console.log(chalk.green('✅ Adoption completed successfully!'));
       console.log();
       
+      // Show conflict resolution summary if conflicts were handled
+      if (detection.conflicts.length > 0) {
+        console.log(chalk.blue('📊 Conflict Resolution Summary:'));
+        console.log(`  Total conflicts: ${detection.conflicts.length}`);
+        
+        const overwrittenFiles = Object.entries(resolutionMap)
+          .filter(([_, resolution]) => resolution === 'overwrite')
+          .map(([path, _]) => path);
+        
+        const skippedFiles = Object.entries(resolutionMap)
+          .filter(([_, resolution]) => resolution === 'keep')
+          .map(([path, _]) => path);
+        
+        if (overwrittenFiles.length > 0) {
+          console.log(chalk.yellow(`  Overwritten: ${overwrittenFiles.length} file(s)`));
+          overwrittenFiles.forEach(file => {
+            console.log(chalk.red(`    ~ ${file}`));
+          });
+        }
+        
+        if (skippedFiles.length > 0) {
+          console.log(chalk.gray(`  Skipped: ${skippedFiles.length} file(s)`));
+          skippedFiles.forEach(file => {
+            console.log(chalk.gray(`    - ${file}`));
+          });
+        }
+        
+        if (conflictBackupId) {
+          console.log();
+          console.log(chalk.blue('📦 Conflict Backup:'), conflictBackupId);
+          console.log(chalk.gray('  To restore overwritten files, run:'));
+          console.log(chalk.cyan(`  kse rollback ${conflictBackupId}`));
+        }
+        
+        console.log();
+      }
+      
       if (steeringStrategy) {
         console.log(chalk.blue('Steering Strategy:'), steeringStrategy);
         if (steeringBackupId) {
@@ -318,17 +422,12 @@ async function adoptCommand(options = {}) {
         result.filesUpdated.forEach(file => console.log(`  ~ ${file}`));
       }
       
-      if (result.filesSkipped.length > 0) {
+      if (result.filesSkipped.length > 0 && detection.conflicts.length === 0) {
+        // Only show this if not already shown in conflict summary
         console.log(chalk.gray('Files skipped:'));
         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:'));
@@ -337,7 +436,7 @@ async function adoptCommand(options = {}) {
       
       if (backupId) {
         console.log();
-        console.log(chalk.blue('📦 Backup:'), backupId);
+        console.log(chalk.blue('📦 Full Backup:'), backupId);
         console.log(chalk.gray('  Run'), chalk.cyan('kse rollback'), chalk.gray('if you need to undo changes'));
       }
       

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.6.3",
-  "description": "Kiro Spec Engine - A spec-driven development engine with steering rules and quality enhancement powered by Ultrawork spirit",
+  "version": "1.7.0",
+  "description": "kiro-spec-engine (kse) - A CLI tool and npm package for spec-driven development with AI coding assistants. NOT the Kiro IDE desktop application.",
   "main": "index.js",
   "bin": {
     "kiro-spec-engine": "./bin/kiro-spec-engine.js",