kiro-spec-engine 1.2.3 → 1.4.0

package/lib/steering/steering-manager.js

@@ -0,0 +1,289 @@
+const fs = require('fs-extra');
+const path = require('path');
+const inquirer = require('inquirer');
+
+/**
+ * SteeringManager - 管理 Steering 文件的独占使用
+ * 
+ * 负责检测、备份、安装和恢复 steering 文件
+ */
+class SteeringManager {
+  constructor() {
+    this.steeringDir = '.kiro/steering';
+    this.backupBaseDir = '.kiro/backups';
+  }
+
+  /**
+   * 检测项目中的 steering 文件
+   * 
+   * @param {string} projectPath - 项目根目录路径
+   * @returns {Promise<Object>} 检测结果
+   */
+  async detectSteering(projectPath) {
+    const steeringPath = path.join(projectPath, this.steeringDir);
+    
+    // 检查 steering 目录是否存在
+    const exists = await fs.pathExists(steeringPath);
+    
+    if (!exists) {
+      return {
+        hasExistingSteering: false,
+        files: [],
+        path: steeringPath
+      };
+    }
+
+    // 读取 steering 目录中的文件
+    const files = await fs.readdir(steeringPath);
+    
+    // 过滤出 .md 文件
+    const mdFiles = files.filter(f => f.endsWith('.md'));
+    
+    // 获取文件详细信息
+    const fileDetails = await Promise.all(
+      mdFiles.map(async (file) => {
+        const filePath = path.join(steeringPath, file);
+        const stats = await fs.stat(filePath);
+        return {
+          name: file,
+          path: filePath,
+          size: stats.size,
+          modified: stats.mtime
+        };
+      })
+    );
+
+    return {
+      hasExistingSteering: mdFiles.length > 0,
+      files: fileDetails,
+      path: steeringPath,
+      count: mdFiles.length
+    };
+  }
+
+  /**
+   * 提示用户选择 steering 策略
+   * 
+   * @param {Object} detection - detectSteering 的返回结果
+   * @returns {Promise<string>} 选择的策略 ('use-kse' | 'use-project')
+   */
+  async promptStrategy(detection) {
+    if (!detection.hasExistingSteering) {
+      // 没有现有 steering 文件，默认使用 kse
+      return 'use-kse';
+    }
+
+    console.log('\n⚠️  Steering Conflict Detected');
+    console.log('━'.repeat(60));
+    console.log(`Found ${detection.count} existing steering file(s) in ${this.steeringDir}:`);
+    console.log('');
+    
+    detection.files.forEach(file => {
+      console.log(`  • ${file.name} (${(file.size / 1024).toFixed(1)} KB)`);
+    });
+    
+    console.log('');
+    console.log('Kiro IDE loads all files in .kiro/steering/, which means you must');
+    console.log('choose between kse steering rules OR your project\'s existing rules.');
+    console.log('');
+
+    const response = await inquirer.prompt([{
+      type: 'list',
+      name: 'strategy',
+      message: 'How would you like to proceed?',
+      choices: [
+        {
+          name: 'Use kse steering (backup existing files) - Recommended for new kse users',
+          value: 'use-kse'
+        },
+        {
+          name: 'Keep existing steering (skip kse steering) - For projects with custom steering rules',
+          value: 'use-project'
+        }
+      ]
+    }]);
+
+    return response.strategy;
+  }
+
+  /**
+   * 备份现有的 steering 文件
+   * 
+   * @param {string} projectPath - 项目根目录路径
+   * @returns {Promise<Object>} 备份结果
+   */
+  async backupSteering(projectPath) {
+    const steeringPath = path.join(projectPath, this.steeringDir);
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupId = `steering-${timestamp}`;
+    const backupPath = path.join(projectPath, this.backupBaseDir, backupId);
+
+    // 检查 steering 目录是否存在
+    const exists = await fs.pathExists(steeringPath);
+    if (!exists) {
+      return {
+        success: false,
+        error: 'Steering directory does not exist',
+        backupId: null,
+        backupPath: null
+      };
+    }
+
+    try {
+      // 创建备份目录
+      await fs.ensureDir(backupPath);
+
+      // 复制所有文件
+      await fs.copy(steeringPath, backupPath, {
+        overwrite: false,
+        errorOnExist: false
+      });
+
+      // 验证备份
+      const backupFiles = await fs.readdir(backupPath);
+      const originalFiles = await fs.readdir(steeringPath);
+
+      return {
+        success: true,
+        backupId,
+        backupPath,
+        filesBackedUp: backupFiles.length,
+        timestamp,
+        verified: backupFiles.length === originalFiles.length
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        backupId,
+        backupPath
+      };
+    }
+  }
+
+  /**
+   * 安装 kse steering 文件
+   * 
+   * @param {string} projectPath - 项目根目录路径
+   * @returns {Promise<Object>} 安装结果
+   */
+  async installKseSteering(projectPath) {
+    const steeringPath = path.join(projectPath, this.steeringDir);
+    const templatePath = path.join(__dirname, '../../template/.kiro/steering');
+
+    try {
+      // 确保 steering 目录存在
+      await fs.ensureDir(steeringPath);
+
+      // 检查模板目录是否存在
+      const templateExists = await fs.pathExists(templatePath);
+      if (!templateExists) {
+        return {
+          success: false,
+          error: 'kse steering template directory not found',
+          filesInstalled: 0
+        };
+      }
+
+      // 复制模板文件
+      const templateFiles = await fs.readdir(templatePath);
+      const mdFiles = templateFiles.filter(f => f.endsWith('.md'));
+
+      let installedCount = 0;
+      for (const file of mdFiles) {
+        const srcPath = path.join(templatePath, file);
+        const destPath = path.join(steeringPath, file);
+        
+        await fs.copy(srcPath, destPath, {
+          overwrite: true
+        });
+        installedCount++;
+      }
+
+      return {
+        success: true,
+        filesInstalled: installedCount,
+        files: mdFiles
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        filesInstalled: 0
+      };
+    }
+  }
+
+  /**
+   * 从备份恢复 steering 文件
+   * 
+   * @param {string} projectPath - 项目根目录路径
+   * @param {string} backupId - 备份 ID
+   * @returns {Promise<Object>} 恢复结果
+   */
+  async restoreSteering(projectPath, backupId) {
+    const steeringPath = path.join(projectPath, this.steeringDir);
+    const backupPath = path.join(projectPath, this.backupBaseDir, backupId);
+
+    // 检查备份是否存在
+    const backupExists = await fs.pathExists(backupPath);
+    if (!backupExists) {
+      return {
+        success: false,
+        error: `Backup not found: ${backupId}`,
+        filesRestored: 0
+      };
+    }
+
+    try {
+      // 清空现有 steering 目录
+      await fs.emptyDir(steeringPath);
+
+      // 从备份恢复
+      await fs.copy(backupPath, steeringPath, {
+        overwrite: true
+      });
+
+      // 验证恢复
+      const restoredFiles = await fs.readdir(steeringPath);
+
+      return {
+        success: true,
+        filesRestored: restoredFiles.length,
+        backupId,
+        files: restoredFiles
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        filesRestored: 0,
+        backupId
+      };
+    }
+  }
+
+  /**
+   * 列出所有可用的 steering 备份
+   * 
+   * @param {string} projectPath - 项目根目录路径
+   * @returns {Promise<Array>} 备份列表
+   */
+  async listBackups(projectPath) {
+    const backupBasePath = path.join(projectPath, this.backupBaseDir);
+    
+    const exists = await fs.pathExists(backupBasePath);
+    if (!exists) {
+      return [];
+    }
+
+    const entries = await fs.readdir(backupBasePath, { withFileTypes: true });
+    const steeringBackups = entries
+      .filter(entry => entry.isDirectory() && entry.name.startsWith('steering-'))
+      .map(entry => entry.name);
+
+    return steeringBackups;
+  }
+}
+
+module.exports = SteeringManager;

package/lib/task/task-claimer.js

@@ -0,0 +1,430 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * TaskClaimer - 任务认领管理
+ * 
+ * 管理任务的认领、释放和状态跟踪
+ */
+class TaskClaimer {
+  constructor() {
+    this.taskFilePattern = /^-\s*\[([ x~-])\](\*)?\s+(.+)$/;
+    this.claimPattern = /\[@([^,]+),\s*claimed:\s*([^\]]+)\]/;
+    this.staleDays = 7;
+  }
+
+  /**
+   * 解析 tasks.md 文件
+   * 
+   * @param {string} tasksPath - tasks.md 文件路径
+   * @returns {Promise<Array>} 任务列表
+   */
+  async parseTasks(tasksPath) {
+    try {
+      const content = await fs.readFile(tasksPath, 'utf8');
+      const lines = content.split('\n');
+      const tasks = [];
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const match = line.match(this.taskFilePattern);
+
+        if (match) {
+          const status = match[1];
+          const isOptional = match[2] === '*';
+          const taskContent = match[3];
+
+          // 提取任务 ID 和标题
+          const taskIdMatch = taskContent.match(/^(\d+(?:\.\d+)*)\s+(.+)$/);
+          
+          if (taskIdMatch) {
+            const taskId = taskIdMatch[1];
+            const titleAndClaim = taskIdMatch[2];
+
+            // 检查是否有认领信息
+            const claimMatch = titleAndClaim.match(this.claimPattern);
+            
+            let title = titleAndClaim;
+            let claimedBy = null;
+            let claimedAt = null;
+
+            if (claimMatch) {
+              title = titleAndClaim.substring(0, claimMatch.index).trim();
+              claimedBy = claimMatch[1];
+              claimedAt = claimMatch[2];
+            }
+
+            tasks.push({
+              lineNumber: i,
+              originalLine: line,
+              status: this.parseStatus(status),
+              isOptional,
+              taskId,
+              title,
+              claimedBy,
+              claimedAt,
+              isStale: claimedAt ? this.isStale(claimedAt) : false
+            });
+          }
+        }
+      }
+
+      return tasks;
+    } catch (error) {
+      throw new Error(`Failed to parse tasks: ${error.message}`);
+    }
+  }
+
+  /**
+   * 解析任务状态
+   * 
+   * @param {string} statusChar - 状态字符
+   * @returns {string} 状态
+   */
+  parseStatus(statusChar) {
+    switch (statusChar) {
+      case ' ':
+        return 'not-started';
+      case 'x':
+        return 'completed';
+      case '-':
+        return 'in-progress';
+      case '~':
+        return 'queued';
+      default:
+        return 'unknown';
+    }
+  }
+
+  /**
+   * 状态转换为字符
+   * 
+   * @param {string} status - 状态
+   * @returns {string} 状态字符
+   */
+  statusToChar(status) {
+    switch (status) {
+      case 'not-started':
+        return ' ';
+      case 'completed':
+        return 'x';
+      case 'in-progress':
+        return '-';
+      case 'queued':
+        return '~';
+      default:
+        return ' ';
+    }
+  }
+
+  /**
+   * 检查认领是否过期
+   * 
+   * @param {string} claimedAt - 认领时间（ISO 字符串）
+   * @returns {boolean} 是否过期
+   */
+  isStale(claimedAt) {
+    try {
+      const claimDate = new Date(claimedAt);
+      const now = new Date();
+      const daysDiff = (now - claimDate) / (1000 * 60 * 60 * 24);
+      return daysDiff > this.staleDays;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * 认领任务
+   * 
+   * @param {string} projectPath - 项目根目录路径
+   * @param {string} specName - Spec 名称
+   * @param {string} taskId - 任务 ID
+   * @param {string} username - 用户名
+   * @param {boolean} force - 是否强制认领
+   * @returns {Promise<Object>} 认领结果
+   */
+  async claimTask(projectPath, specName, taskId, username, force = false) {
+    const tasksPath = path.join(projectPath, '.kiro/specs', specName, 'tasks.md');
+
+    try {
+      // 检查文件是否存在
+      const exists = await fs.pathExists(tasksPath);
+      if (!exists) {
+        return {
+          success: false,
+          error: `tasks.md not found for spec: ${specName}`
+        };
+      }
+
+      // 解析任务
+      const tasks = await this.parseTasks(tasksPath);
+      const task = tasks.find(t => t.taskId === taskId);
+
+      if (!task) {
+        return {
+          success: false,
+          error: `Task not found: ${taskId}`
+        };
+      }
+
+      // 检查是否已被认领
+      if (task.claimedBy && task.claimedBy !== username && !force) {
+        return {
+          success: false,
+          error: `Task already claimed by ${task.claimedBy}`,
+          needsForce: true,
+          currentClaim: {
+            username: task.claimedBy,
+            claimedAt: task.claimedAt,
+            isStale: task.isStale
+          }
+        };
+      }
+
+      // 读取文件内容
+      const content = await fs.readFile(tasksPath, 'utf8');
+      const lines = content.split('\n');
+
+      // 构建新的任务行
+      const claimTimestamp = new Date().toISOString();
+      const statusChar = this.statusToChar('in-progress');
+      const optionalMarker = task.isOptional ? '*' : '';
+      const newLine = `- [${statusChar}]${optionalMarker} ${taskId} ${task.title} [@${username}, claimed: ${claimTimestamp}]`;
+
+      // 替换任务行
+      lines[task.lineNumber] = newLine;
+
+      // 写回文件
+      await fs.writeFile(tasksPath, lines.join('\n'), 'utf8');
+
+      return {
+        success: true,
+        taskId,
+        username,
+        claimedAt: claimTimestamp,
+        previousClaim: task.claimedBy ? {
+          username: task.claimedBy,
+          claimedAt: task.claimedAt
+        } : null
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * 释放任务认领
+   * 
+   * @param {string} projectPath - 项目根目录路径
+   * @param {string} specName - Spec 名称
+   * @param {string} taskId - 任务 ID
+   * @param {string} username - 用户名
+   * @returns {Promise<Object>} 释放结果
+   */
+  async unclaimTask(projectPath, specName, taskId, username) {
+    const tasksPath = path.join(projectPath, '.kiro/specs', specName, 'tasks.md');
+
+    try {
+      // 检查文件是否存在
+      const exists = await fs.pathExists(tasksPath);
+      if (!exists) {
+        return {
+          success: false,
+          error: `tasks.md not found for spec: ${specName}`
+        };
+      }
+
+      // 解析任务
+      const tasks = await this.parseTasks(tasksPath);
+      const task = tasks.find(t => t.taskId === taskId);
+
+      if (!task) {
+        return {
+          success: false,
+          error: `Task not found: ${taskId}`
+        };
+      }
+
+      // 检查是否被当前用户认领
+      if (!task.claimedBy) {
+        return {
+          success: false,
+          error: 'Task is not claimed'
+        };
+      }
+
+      if (task.claimedBy !== username) {
+        return {
+          success: false,
+          error: `Task is claimed by ${task.claimedBy}, not ${username}`
+        };
+      }
+
+      // 读取文件内容
+      const content = await fs.readFile(tasksPath, 'utf8');
+      const lines = content.split('\n');
+
+      // 构建新的任务行（移除认领信息，重置状态）
+      const statusChar = this.statusToChar('not-started');
+      const optionalMarker = task.isOptional ? '*' : '';
+      const newLine = `- [${statusChar}]${optionalMarker} ${taskId} ${task.title}`;
+
+      // 替换任务行
+      lines[task.lineNumber] = newLine;
+
+      // 写回文件
+      await fs.writeFile(tasksPath, lines.join('\n'), 'utf8');
+
+      return {
+        success: true,
+        taskId,
+        username,
+        unclaimedAt: new Date().toISOString()
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * 获取已认领的任务列表
+   * 
+   * @param {string} projectPath - 项目根目录路径
+   * @param {string} specName - Spec 名称
+   * @returns {Promise<Array>} 已认领的任务列表
+   */
+  async getClaimedTasks(projectPath, specName) {
+    const tasksPath = path.join(projectPath, '.kiro/specs', specName, 'tasks.md');
+
+    try {
+      const exists = await fs.pathExists(tasksPath);
+      if (!exists) {
+        return [];
+      }
+
+      const tasks = await this.parseTasks(tasksPath);
+      
+      return tasks
+        .filter(task => task.claimedBy)
+        .map(task => ({
+          specName,
+          taskId: task.taskId,
+          taskTitle: task.title,
+          claimedBy: task.claimedBy,
+          claimedAt: task.claimedAt,
+          status: task.status,
+          isStale: task.isStale,
+          isOptional: task.isOptional
+        }));
+    } catch (error) {
+      return [];
+    }
+  }
+
+  /**
+   * 更新任务状态
+   * 
+   * @param {string} projectPath - 项目根目录路径
+   * @param {string} specName - Spec 名称
+   * @param {string} taskId - 任务 ID
+   * @param {string} status - 新状态
+   * @returns {Promise<Object>} 更新结果
+   */
+  async updateTaskStatus(projectPath, specName, taskId, status) {
+    const tasksPath = path.join(projectPath, '.kiro/specs', specName, 'tasks.md');
+
+    try {
+      const exists = await fs.pathExists(tasksPath);
+      if (!exists) {
+        return {
+          success: false,
+          error: `tasks.md not found for spec: ${specName}`
+        };
+      }
+
+      const tasks = await this.parseTasks(tasksPath);
+      const task = tasks.find(t => t.taskId === taskId);
+
+      if (!task) {
+        return {
+          success: false,
+          error: `Task not found: ${taskId}`
+        };
+      }
+
+      // 读取文件内容
+      const content = await fs.readFile(tasksPath, 'utf8');
+      const lines = content.split('\n');
+
+      // 构建新的任务行
+      const statusChar = this.statusToChar(status);
+      const optionalMarker = task.isOptional ? '*' : '';
+      
+      let newLine = `- [${statusChar}]${optionalMarker} ${taskId} ${task.title}`;
+      
+      // 保留认领信息（如果有）
+      if (task.claimedBy) {
+        newLine += ` [@${task.claimedBy}, claimed: ${task.claimedAt}]`;
+      }
+
+      // 替换任务行
+      lines[task.lineNumber] = newLine;
+
+      // 写回文件
+      await fs.writeFile(tasksPath, lines.join('\n'), 'utf8');
+
+      return {
+        success: true,
+        taskId,
+        oldStatus: task.status,
+        newStatus: status
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * 获取所有 Spec 的已认领任务
+   * 
+   * @param {string} projectPath - 项目根目录路径
+   * @returns {Promise<Array>} 所有已认领的任务
+   */
+  async getAllClaimedTasks(projectPath) {
+    const specsPath = path.join(projectPath, '.kiro/specs');
+    
+    try {
+      const exists = await fs.pathExists(specsPath);
+      if (!exists) {
+        return [];
+      }
+
+      const entries = await fs.readdir(specsPath, { withFileTypes: true });
+      const specDirs = entries.filter(entry => entry.isDirectory());
+
+      const allClaimedTasks = [];
+
+      for (const specDir of specDirs) {
+        const specName = specDir.name;
+        const claimedTasks = await this.getClaimedTasks(projectPath, specName);
+        allClaimedTasks.push(...claimedTasks);
+      }
+
+      return allClaimedTasks;
+    } catch (error) {
+      return [];
+    }
+  }
+}
+
+module.exports = TaskClaimer;