scene-capability-engine 3.0.0

package/lib/steering/steering-compliance-checker.js

@@ -0,0 +1,73 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * SteeringComplianceChecker - Validates steering directory compliance
+ * 
+ * Ensures the .kiro/steering/ directory contains only allowed files
+ * and no subdirectories to prevent context pollution and excessive
+ * token consumption in AI sessions.
+ */
+class SteeringComplianceChecker {
+  /**
+   * Get list of allowed files in steering directory
+   * 
+   * @returns {string[]} Array of allowed file names
+   */
+  getAllowedFiles() {
+    return [
+      'CORE_PRINCIPLES.md',
+      'ENVIRONMENT.md',
+      'CURRENT_CONTEXT.md',
+      'RULES_GUIDE.md'
+    ];
+  }
+
+  /**
+   * Check if steering directory is compliant
+   * 
+   * @param {string} steeringPath - Path to steering directory
+   * @returns {ComplianceResult} Result with status and violations
+   */
+  check(steeringPath) {
+    // Non-existent directory is compliant
+    if (!fs.existsSync(steeringPath)) {
+      return { compliant: true };
+    }
+
+    const violations = [];
+    const allowedFiles = this.getAllowedFiles();
+    
+    try {
+      const entries = fs.readdirSync(steeringPath, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          // Subdirectories are not allowed
+          violations.push({
+            type: 'subdirectory',
+            name: entry.name,
+            path: path.join(steeringPath, entry.name)
+          });
+        } else if (!allowedFiles.includes(entry.name)) {
+          // File not in allowlist
+          violations.push({
+            type: 'disallowed_file',
+            name: entry.name,
+            path: path.join(steeringPath, entry.name)
+          });
+        }
+      }
+      
+      return {
+        compliant: violations.length === 0,
+        violations
+      };
+    } catch (error) {
+      // Re-throw unexpected errors
+      throw error;
+    }
+  }
+}
+
+module.exports = SteeringComplianceChecker;

package/lib/steering/steering-loader.js

@@ -0,0 +1,144 @@
+/**
+ * SteeringLoader - 统一加载并合并 L1-L4 四层 Steering 约束
+ *
+ * L1: CORE_PRINCIPLES.md (通用约束)
+ * L2: ENVIRONMENT.md (环境约束)
+ * L3: CURRENT_CONTEXT.md (全局上下文)
+ * L4: .kiro/specs/{spec-name}/steering.md (Spec 级约束, via SpecSteering)
+ *
+ * 单 Agent 模式下跳过 L4。
+ *
+ * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 6.4
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+const { SpecSteering } = require('./spec-steering');
+const { MultiAgentConfig } = require('../collab/multi-agent-config');
+
+const STEERING_DIR = '.kiro/steering';
+
+const LAYER_FILES = {
+  l1: 'CORE_PRINCIPLES.md',
+  l2: 'ENVIRONMENT.md',
+  l3: 'CURRENT_CONTEXT.md',
+};
+
+class SteeringLoader {
+  /**
+   * @param {string} workspaceRoot - Absolute path to the project root
+   */
+  constructor(workspaceRoot) {
+    this._workspaceRoot = workspaceRoot;
+    this._specSteering = new SpecSteering(workspaceRoot);
+    this._multiAgentConfig = new MultiAgentConfig(workspaceRoot);
+  }
+
+  /**
+   * 加载所有层级的 Steering 内容。
+   * 单 Agent 模式下跳过 L4。
+   *
+   * @param {string|null} specName - 当前 Spec 名称，null 时跳过 L4
+   * @returns {Promise<{
+   *   l1: string|null,
+   *   l2: string|null,
+   *   l3: string|null,
+   *   l4: {constraints: string[], notes: string[], decisions: string[]}|null
+   * }>}
+   */
+  async load(specName = null) {
+    const [l1, l2, l3] = await Promise.all([
+      this._loadLayerFile('l1'),
+      this._loadLayerFile('l2'),
+      this._loadLayerFile('l3'),
+    ]);
+
+    let l4 = null;
+    if (specName) {
+      const enabled = await this._multiAgentConfig.isEnabled();
+      if (enabled) {
+        l4 = await this._loadL4(specName);
+      }
+    }
+
+    return { l1, l2, l3, l4 };
+  }
+
+  /**
+   * 加载并合并所有层级，L4 覆盖 L1-L3 的冲突项。
+   * L4 内容追加在最后，使其优先级最高。
+   *
+   * @param {string|null} specName
+   * @returns {Promise<{layers: object, merged: string}>}
+   */
+  async loadMerged(specName = null) {
+    const layers = await this.load(specName);
+    const parts = [];
+
+    if (layers.l1) {
+      parts.push(layers.l1);
+    }
+    if (layers.l2) {
+      parts.push(layers.l2);
+    }
+    if (layers.l3) {
+      parts.push(layers.l3);
+    }
+    if (layers.l4) {
+      parts.push(this._formatL4(layers.l4));
+    }
+
+    return {
+      layers,
+      merged: parts.join('\n\n---\n\n'),
+    };
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────
+
+  /**
+   * Load a L1/L2/L3 layer file. Returns null if the file doesn't exist.
+   * @param {'l1'|'l2'|'l3'} layerKey
+   * @returns {Promise<string|null>}
+   */
+  async _loadLayerFile(layerKey) {
+    const filename = LAYER_FILES[layerKey];
+    const filePath = path.join(this._workspaceRoot, STEERING_DIR, filename);
+
+    try {
+      const exists = await fs.pathExists(filePath);
+      if (!exists) {
+        return null;
+      }
+      return await fs.readFile(filePath, 'utf8');
+    } catch (err) {
+      console.warn(`[SteeringLoader] Failed to read ${layerKey} (${filename}): ${err.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Load L4 via SpecSteering. Returns null if the file doesn't exist or is corrupted.
+   * @param {string} specName
+   * @returns {Promise<{constraints: string[], notes: string[], decisions: string[]}|null>}
+   */
+  async _loadL4(specName) {
+    try {
+      return await this._specSteering.read(specName);
+    } catch (err) {
+      console.warn(`[SteeringLoader] Failed to read L4 for ${specName}: ${err.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Format L4 structured object back to a Markdown string for merging.
+   * @param {{constraints: string[], notes: string[], decisions: string[]}} l4
+   * @returns {string}
+   */
+  _formatL4(l4) {
+    return this._specSteering.format(l4);
+  }
+}
+
+module.exports = { SteeringLoader };

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/index.js

@@ -0,0 +1,12 @@
+/**
+ * Task module exports
+ * @module lib/task
+ */
+
+const TaskClaimer = require('./task-claimer');
+const { TaskStatusStore } = require('./task-status-store');
+
+module.exports = {
+  TaskClaimer,
+  TaskStatusStore
+};