kiro-spec-engine 1.4.4 → 1.5.5

package/lib/adoption/adoption-strategy.js

@@ -41,14 +41,12 @@ class AdoptionStrategy {
   /**
    * Gets the path to template directory
    * This would be embedded in the kse package
-   * For now, we'll use a placeholder
    * 
    * @returns {string}
    */
   getTemplatePath() {
-    // In production, this would be: path.join(__dirname, '../../templates/kiro')
-    // For now, return a placeholder that can be configured
-    return path.join(__dirname, '../../templates/kiro');
+    // Template is at template/.kiro/ in the package
+    return path.join(__dirname, '../../template/.kiro');
   }
 
   /**
@@ -85,10 +83,11 @@ class AdoptionStrategy {
    * @param {Object} options - Copy options
    * @param {boolean} options.overwrite - Whether to overwrite existing files
    * @param {string[]} options.skip - Files to skip
+   * @param {Object} options.resolutionMap - Map of file paths to resolutions ('keep' | 'overwrite')
    * @returns {Promise<{created: string[], updated: string[], skipped: string[]}>}
    */
   async copyTemplateFiles(projectPath, options = {}) {
-    const { overwrite = false, skip = [] } = options;
+    const { overwrite = false, skip = [], resolutionMap = {} } = options;
     const kiroPath = this.getKiroPath(projectPath);
     const templatePath = this.getTemplatePath();
     
@@ -106,15 +105,12 @@ class AdoptionStrategy {
     
     // Define template structure
     const templateFiles = [
+      'README.md',
       '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'
+      'specs/SPEC_WORKFLOW_GUIDE.md'
     ];
     
     for (const file of templateFiles) {
@@ -124,6 +120,15 @@ class AdoptionStrategy {
         continue;
       }
       
+      // Check resolution map for this file
+      if (resolutionMap[file]) {
+        if (resolutionMap[file] === 'keep') {
+          skipped.push(file);
+          continue;
+        }
+        // If 'overwrite', proceed with copying
+      }
+      
       const sourcePath = path.join(templatePath, file);
       const destPath = path.join(kiroPath, file);
       
@@ -137,13 +142,19 @@ class AdoptionStrategy {
       // Check if destination exists
       const destExists = await pathExists(destPath);
       
-      if (destExists && !overwrite) {
+      // Determine if we should overwrite
+      let shouldOverwrite = overwrite;
+      if (resolutionMap[file] === 'overwrite') {
+        shouldOverwrite = true;
+      }
+      
+      if (destExists && !shouldOverwrite) {
         skipped.push(file);
         continue;
       }
       
       try {
-        await safeCopy(sourcePath, destPath, { overwrite });
+        await safeCopy(sourcePath, destPath, { overwrite: shouldOverwrite });
         
         if (destExists) {
           updated.push(file);
@@ -263,7 +274,7 @@ class PartialAdoption extends AdoptionStrategy {
    * @returns {Promise<AdoptionResult>}
    */
   async execute(projectPath, mode, options = {}) {
-    const { kseVersion = '1.0.0', dryRun = false, backupId = null } = options;
+    const { kseVersion = '1.0.0', dryRun = false, backupId = null, force = false, resolutionMap = {} } = options;
     
     const filesCreated = [];
     const filesUpdated = [];
@@ -326,8 +337,8 @@ class PartialAdoption extends AdoptionStrategy {
         filesCreated.push('backups/');
       }
       
-      // Copy template files (don't overwrite existing)
-      const copyResult = await this.copyTemplateFiles(projectPath, { overwrite: false });
+      // Copy template files (overwrite if force is enabled)
+      const copyResult = await this.copyTemplateFiles(projectPath, { overwrite: force, resolutionMap });
       filesCreated.push(...copyResult.created);
       filesUpdated.push(...copyResult.updated);
       filesSkipped.push(...copyResult.skipped);

package/lib/adoption/conflict-resolver.js

@@ -0,0 +1,239 @@
+/**
+ * Conflict Resolver
+ * 
+ * Manages interactive conflict resolution prompts and user decisions.
+ * Provides three-tier resolution: skip-all, overwrite-all, or review-each.
+ */
+
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const path = require('path');
+const DiffViewer = require('./diff-viewer');
+
+/**
+ * ConflictResolver class for interactive conflict resolution
+ */
+class ConflictResolver {
+  constructor() {
+    this.diffViewer = new DiffViewer();
+  }
+
+  /**
+   * Displays conflict summary grouped by category
+   * 
+   * @param {FileConflict[]} conflicts - Array of conflicts
+   * @returns {void}
+   */
+  displayConflictSummary(conflicts) {
+    console.log();
+    console.log(chalk.yellow('⚠️  Conflicts Detected'));
+    console.log(chalk.yellow('═══════════════════════════════════════════════════════'));
+    console.log();
+    
+    // Categorize conflicts
+    const categorized = this.categorizeConflicts(conflicts);
+    
+    // Display by category
+    if (categorized.steering.length > 0) {
+      console.log(chalk.blue('Steering Files:'));
+      categorized.steering.forEach(c => console.log(`  - ${c.path}`));
+      console.log();
+    }
+    
+    if (categorized.documentation.length > 0) {
+      console.log(chalk.blue('Documentation:'));
+      categorized.documentation.forEach(c => console.log(`  - ${c.path}`));
+      console.log();
+    }
+    
+    if (categorized.tools.length > 0) {
+      console.log(chalk.blue('Tools:'));
+      categorized.tools.forEach(c => console.log(`  - ${c.path}`));
+      console.log();
+    }
+    
+    if (categorized.other.length > 0) {
+      console.log(chalk.blue('Other:'));
+      categorized.other.forEach(c => console.log(`  - ${c.path}`));
+      console.log();
+    }
+    
+    console.log(chalk.yellow(`Total: ${conflicts.length} conflict(s)`));
+    console.log(chalk.yellow('═══════════════════════════════════════════════════════'));
+    console.log();
+  }
+
+  /**
+   * Categorizes conflicts by type
+   * 
+   * @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/')
+      ),
+      tools: conflicts.filter(c => c.path.startsWith('tools/')),
+      other: conflicts.filter(c => 
+        !c.path.startsWith('steering/') && 
+        !c.path.startsWith('tools/') && 
+        !c.path.endsWith('.md')
+      )
+    };
+  }
+
+  /**
+   * Prompts user for overall conflict resolution strategy
+   * 
+   * @param {FileConflict[]} conflicts - Array of detected conflicts
+   * @returns {Promise<ConflictStrategy>} - 'skip-all' | 'overwrite-all' | 'review-each'
+   */
+  async promptStrategy(conflicts) {
+    const { strategy } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'strategy',
+        message: 'How would you like to handle these conflicts?',
+        choices: [
+          {
+            name: 'Skip conflicting files (keep existing files)',
+            value: 'skip-all'
+          },
+          {
+            name: 'Overwrite conflicting files (backup will be created)',
+            value: 'overwrite-all'
+          },
+          {
+            name: 'Review conflicts one by one',
+            value: 'review-each'
+          }
+        ],
+        default: 'skip-all'
+      }
+    ]);
+    
+    return strategy;
+  }
+
+  /**
+   * Prompts user for resolution of a single file conflict
+   * 
+   * @param {FileConflict} conflict - The conflict to resolve
+   * @param {number} currentIndex - Current conflict number (for display)
+   * @param {number} totalConflicts - Total number of conflicts
+   * @param {string} projectPath - Project root path
+   * @returns {Promise<FileResolution>} - 'keep' | 'overwrite'
+   */
+  async promptFileResolution(conflict, currentIndex, totalConflicts, projectPath) {
+    console.log();
+    console.log(chalk.blue('─────────────────────────────────────────────────────'));
+    console.log(chalk.blue(`Conflict ${currentIndex} of ${totalConflicts}`));
+    console.log(chalk.blue('─────────────────────────────────────────────────────'));
+    console.log();
+    console.log(chalk.cyan('File:'), conflict.path);
+    console.log();
+    
+    let resolution = null;
+    
+    while (resolution === null) {
+      const { action } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'action',
+          message: 'What would you like to do?',
+          choices: [
+            {
+              name: 'Keep existing file',
+              value: 'keep'
+            },
+            {
+              name: 'Use template file (backup will be created)',
+              value: 'overwrite'
+            },
+            {
+              name: 'View diff',
+              value: 'view-diff'
+            }
+          ],
+          default: 'keep'
+        }
+      ]);
+      
+      if (action === 'view-diff') {
+        // Show diff
+        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);
+        
+        // Re-prompt with only keep/overwrite options
+        const { finalAction } = await inquirer.prompt([
+          {
+            type: 'list',
+            name: 'finalAction',
+            message: 'After viewing the diff, what would you like to do?',
+            choices: [
+              {
+                name: 'Keep existing file',
+                value: 'keep'
+              },
+              {
+                name: 'Use template file (backup will be created)',
+                value: 'overwrite'
+              }
+            ],
+            default: 'keep'
+          }
+        ]);
+        
+        resolution = finalAction;
+      } else {
+        resolution = action;
+      }
+    }
+    
+    return resolution;
+  }
+
+  /**
+   * Processes all conflicts based on strategy and returns resolution map
+   * 
+   * @param {FileConflict[]} conflicts - Array of conflicts
+   * @param {ConflictStrategy} strategy - Overall strategy
+   * @param {string} projectPath - Project root path
+   * @returns {Promise<ResolutionMap>} - Map of file paths to resolutions
+   */
+  async resolveConflicts(conflicts, strategy, projectPath) {
+    const resolutionMap = {};
+    
+    if (strategy === 'skip-all') {
+      // Mark all as 'keep'
+      conflicts.forEach(conflict => {
+        resolutionMap[conflict.path] = 'keep';
+      });
+    } else if (strategy === 'overwrite-all') {
+      // Mark all as 'overwrite'
+      conflicts.forEach(conflict => {
+        resolutionMap[conflict.path] = 'overwrite';
+      });
+    } else if (strategy === 'review-each') {
+      // Prompt for each conflict
+      for (let i = 0; i < conflicts.length; i++) {
+        const conflict = conflicts[i];
+        const resolution = await this.promptFileResolution(
+          conflict,
+          i + 1,
+          conflicts.length,
+          projectPath
+        );
+        resolutionMap[conflict.path] = resolution;
+      }
+    }
+    
+    return resolutionMap;
+  }
+}
+
+module.exports = ConflictResolver;

package/lib/adoption/diff-viewer.js

@@ -0,0 +1,226 @@
+/**
+ * Diff Viewer
+ * 
+ * Displays file differences in a user-friendly format for conflict review.
+ * Shows metadata comparison and text diffs for files during adoption.
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+const { pathExists } = require('../utils/fs-utils');
+
+/**
+ * DiffViewer class for displaying file comparisons
+ */
+class DiffViewer {
+  /**
+   * Gets file metadata for comparison
+   * 
+   * @param {string} filePath - Path to file
+   * @returns {Promise<FileMetadata>}
+   */
+  async getFileMetadata(filePath) {
+    const exists = await pathExists(filePath);
+    
+    if (!exists) {
+      return {
+        path: filePath,
+        size: 0,
+        sizeFormatted: '0 B',
+        modified: null,
+        modifiedFormatted: 'N/A',
+        isText: false,
+        isBinary: false,
+        exists: false
+      };
+    }
+    
+    const stats = await fs.stat(filePath);
+    const size = stats.size;
+    const modified = stats.mtime.toISOString();
+    
+    // Format size
+    const sizeFormatted = this.formatSize(size);
+    
+    // Format date
+    const modifiedFormatted = this.formatDate(stats.mtime);
+    
+    // Detect if file is text or binary
+    const isText = await this.isTextFile(filePath);
+    const isBinary = !isText;
+    
+    return {
+      path: filePath,
+      size,
+      sizeFormatted,
+      modified,
+      modifiedFormatted,
+      isText,
+      isBinary,
+      exists: true
+    };
+  }
+
+  /**
+   * Formats file size in human-readable format
+   * 
+   * @param {number} bytes - File size in bytes
+   * @returns {string}
+   */
+  formatSize(bytes) {
+    if (bytes === 0) return '0 B';
+    
+    const units = ['B', 'KB', 'MB', 'GB'];
+    const k = 1024;
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    
+    return `${(bytes / Math.pow(k, i)).toFixed(1)} ${units[i]}`;
+  }
+
+  /**
+   * Formats date in human-readable format
+   * 
+   * @param {Date} date - Date object
+   * @returns {string}
+   */
+  formatDate(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    const hours = String(date.getHours()).padStart(2, '0');
+    const minutes = String(date.getMinutes()).padStart(2, '0');
+    const seconds = String(date.getSeconds()).padStart(2, '0');
+    
+    return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+  }
+
+  /**
+   * Detects if a file is text or binary
+   * 
+   * @param {string} filePath - Path to file
+   * @returns {Promise<boolean>}
+   */
+  async isTextFile(filePath) {
+    try {
+      // Read first 8KB to detect binary content
+      const buffer = Buffer.alloc(8192);
+      const fd = await fs.open(filePath, 'r');
+      const { bytesRead } = await fd.read(buffer, 0, 8192, 0);
+      await fd.close();
+      
+      // Check for null bytes (common in binary files)
+      for (let i = 0; i < bytesRead; i++) {
+        if (buffer[i] === 0) {
+          return false;
+        }
+      }
+      
+      return true;
+    } catch (error) {
+      // If we can't read it, assume binary
+      return false;
+    }
+  }
+
+  /**
+   * Displays a summary diff between existing and template files
+   * 
+   * @param {string} existingPath - Path to existing file
+   * @param {string} templatePath - Path to template file
+   * @returns {Promise<void>}
+   */
+  async showDiff(existingPath, templatePath) {
+    console.log();
+    console.log(chalk.blue('═══════════════════════════════════════════════════════'));
+    console.log(chalk.blue('Comparing:'), chalk.cyan(path.basename(existingPath)));
+    console.log(chalk.blue('═══════════════════════════════════════════════════════'));
+    console.log();
+    
+    // Get metadata for both files
+    const existingMeta = await this.getFileMetadata(existingPath);
+    const templateMeta = await this.getFileMetadata(templatePath);
+    
+    // Display metadata comparison
+    console.log(chalk.yellow('Existing File:'));
+    console.log(`  Size: ${existingMeta.sizeFormatted}`);
+    console.log(`  Modified: ${existingMeta.modifiedFormatted}`);
+    console.log();
+    
+    console.log(chalk.green('Template File:'));
+    console.log(`  Size: ${templateMeta.sizeFormatted}`);
+    console.log(`  Modified: ${templateMeta.modifiedFormatted}`);
+    console.log();
+    
+    // Show diff content if both are text files
+    if (existingMeta.isText && templateMeta.isText) {
+      await this.showLineDiff(existingPath, templatePath, 10);
+    } else if (existingMeta.isBinary || templateMeta.isBinary) {
+      console.log(chalk.gray('⚠️  Binary file - detailed diff not available'));
+      console.log(chalk.gray('   Open files in an editor to compare'));
+    }
+    
+    console.log();
+    console.log(chalk.blue('═══════════════════════════════════════════════════════'));
+    console.log();
+  }
+
+  /**
+   * Displays first N lines of differences
+   * 
+   * @param {string} existingPath - Path to existing file
+   * @param {string} templatePath - Path to template file
+   * @param {number} maxLines - Maximum lines to show (default: 10)
+   * @returns {Promise<void>}
+   */
+  async showLineDiff(existingPath, templatePath, maxLines = 10) {
+    try {
+      const existingContent = await fs.readFile(existingPath, 'utf-8');
+      const templateContent = await fs.readFile(templatePath, 'utf-8');
+      
+      const existingLines = existingContent.split('\n');
+      const templateLines = templateContent.split('\n');
+      
+      console.log(chalk.blue('First differences:'));
+      console.log();
+      
+      let diffsShown = 0;
+      const maxLineNum = Math.max(existingLines.length, templateLines.length);
+      
+      for (let i = 0; i < maxLineNum && diffsShown < maxLines; i++) {
+        const existingLine = existingLines[i] || '';
+        const templateLine = templateLines[i] || '';
+        
+        if (existingLine !== templateLine) {
+          console.log(chalk.gray(`  Line ${i + 1}:`));
+          
+          if (existingLine) {
+            console.log(chalk.red(`    - ${existingLine.substring(0, 80)}`));
+          }
+          
+          if (templateLine) {
+            console.log(chalk.green(`    + ${templateLine.substring(0, 80)}`));
+          }
+          
+          console.log();
+          diffsShown++;
+        }
+      }
+      
+      if (diffsShown === 0) {
+        console.log(chalk.gray('  No differences found in first 10 lines'));
+        console.log();
+      } else if (diffsShown >= maxLines) {
+        console.log(chalk.gray(`  ... (showing first ${maxLines} differences)`));
+        console.log();
+      }
+      
+      console.log(chalk.gray('[Note: Full diff available by opening files in editor]'));
+    } catch (error) {
+      console.log(chalk.red('⚠️  Unable to generate diff'));
+      console.log(chalk.gray(`   ${error.message}`));
+    }
+  }
+}
+
+module.exports = DiffViewer;