scene-capability-engine 3.0.0

package/lib/spec-gate/rules/default-rules.js

@@ -0,0 +1,156 @@
+const fs = require('fs-extra');
+const path = require('path');
+const docsCommand = require('../../commands/docs');
+
+function createDefaultRules(projectPath = process.cwd()) {
+  return [
+    {
+      id: 'mandatory',
+      description: 'Verify mandatory Spec files exist',
+      async execute(context) {
+        const specPath = path.join(projectPath, '.kiro', 'specs', context.specId);
+        const requiredFiles = ['requirements.md', 'design.md', 'tasks.md'];
+        const checks = await Promise.all(requiredFiles.map(async fileName => {
+          const filePath = path.join(specPath, fileName);
+          const exists = await fs.pathExists(filePath);
+          return { fileName, exists };
+        }));
+
+        const missing = checks.filter(item => !item.exists).map(item => item.fileName);
+        const passRatio = checks.filter(item => item.exists).length / requiredFiles.length;
+
+        return {
+          passed: missing.length === 0,
+          ratio: passRatio,
+          details: {
+            requiredFiles,
+            missing
+          },
+          warnings: missing.length > 0 ? [`Missing files: ${missing.join(', ')}`] : []
+        };
+      }
+    },
+    {
+      id: 'tests',
+      description: 'Verify tasks include explicit validation intent',
+      async execute(context) {
+        const tasksPath = path.join(projectPath, '.kiro', 'specs', context.specId, 'tasks.md');
+        if (!await fs.pathExists(tasksPath)) {
+          return {
+            passed: false,
+            ratio: 0,
+            details: { reason: 'tasks.md missing' },
+            warnings: ['tasks.md missing']
+          };
+        }
+
+        const content = await fs.readFile(tasksPath, 'utf8');
+        const hasValidationHints = /验证|Validation|Acceptance/i.test(content);
+
+        return {
+          passed: hasValidationHints,
+          ratio: hasValidationHints ? 1 : 0,
+          details: {
+            hasValidationHints
+          },
+          warnings: hasValidationHints ? [] : ['No validation markers found in tasks.md']
+        };
+      }
+    },
+    {
+      id: 'docs',
+      description: 'Validate document structure compatibility',
+      async execute(context) {
+        const exitCode = await docsCommand('validate', {
+          spec: context.specId
+        });
+
+        return {
+          passed: exitCode === 0,
+          ratio: exitCode === 0 ? 1 : 0,
+          details: {
+            exitCode
+          },
+          warnings: exitCode === 0 ? [] : [`docs validate returned exit code ${exitCode}`]
+        };
+      }
+    },
+    {
+      id: 'config_consistency',
+      description: 'Verify project-level KSE config baseline exists',
+      async execute() {
+        const kiroDir = path.join(projectPath, '.kiro');
+        const configDir = path.join(kiroDir, 'config');
+        const hasKiro = await fs.pathExists(kiroDir);
+        const hasConfig = await fs.pathExists(configDir);
+
+        const ratio = hasKiro && hasConfig ? 1 : hasKiro ? 0.5 : 0;
+        const warnings = [];
+        if (!hasKiro) {
+          warnings.push('.kiro directory missing');
+        }
+        if (hasKiro && !hasConfig) {
+          warnings.push('.kiro/config directory missing');
+        }
+
+        return {
+          passed: hasKiro,
+          ratio,
+          details: {
+            hasKiro,
+            hasConfig
+          },
+          warnings
+        };
+      }
+    },
+    {
+      id: 'traceability',
+      description: 'Verify requirement-design-task traceability hints',
+      async execute(context) {
+        const specPath = path.join(projectPath, '.kiro', 'specs', context.specId);
+        const designPath = path.join(specPath, 'design.md');
+        const tasksPath = path.join(specPath, 'tasks.md');
+
+        const hasDesign = await fs.pathExists(designPath);
+        const hasTasks = await fs.pathExists(tasksPath);
+
+        if (!hasDesign || !hasTasks) {
+          return {
+            passed: false,
+            ratio: 0,
+            details: {
+              hasDesign,
+              hasTasks
+            },
+            warnings: ['design.md or tasks.md missing']
+          };
+        }
+
+        const [designContent, tasksContent] = await Promise.all([
+          fs.readFile(designPath, 'utf8'),
+          fs.readFile(tasksPath, 'utf8')
+        ]);
+
+        const hasMapping = /Mapping|映射|Requirement/i.test(designContent);
+        const hasTaskReferences = /Requirement|Design|需求|设计/i.test(tasksContent);
+        const scoreParts = [hasMapping, hasTaskReferences].filter(Boolean).length;
+
+        return {
+          passed: hasMapping && hasTaskReferences,
+          ratio: scoreParts / 2,
+          details: {
+            hasMapping,
+            hasTaskReferences
+          },
+          warnings: hasMapping && hasTaskReferences ? [] : ['Traceability links are incomplete']
+        };
+      }
+    }
+  ];
+}
+
+module.exports = {
+  createDefaultRules
+};
+

package/lib/spec-gate/rules/rule-registry.js

@@ -0,0 +1,51 @@
+class RuleRegistry {
+  constructor(initialRules = []) {
+    this.rules = new Map();
+    initialRules.forEach(rule => this.register(rule));
+  }
+
+  register(rule) {
+    if (!rule || !rule.id || typeof rule.execute !== 'function') {
+      throw new Error('Invalid gate rule: expected id and execute()');
+    }
+
+    this.rules.set(rule.id, rule);
+  }
+
+  setEnabled(ruleId, enabled) {
+    const rule = this.rules.get(ruleId);
+    if (!rule) {
+      throw new Error(`Rule not found: ${ruleId}`);
+    }
+
+    rule.enabled = !!enabled;
+  }
+
+  get(ruleId) {
+    return this.rules.get(ruleId);
+  }
+
+  list() {
+    return Array.from(this.rules.values());
+  }
+
+  listEnabled(policyRules = {}) {
+    return this.list().filter(rule => {
+      const policy = policyRules[rule.id];
+      if (!policy) {
+        return false;
+      }
+
+      if (typeof rule.enabled === 'boolean') {
+        return rule.enabled;
+      }
+
+      return policy.enabled !== false;
+    });
+  }
+}
+
+module.exports = {
+  RuleRegistry
+};
+

package/lib/steering/adoption-config.js

@@ -0,0 +1,164 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * AdoptionConfig - 管理 adoption-config.json 配置文件
+ * 
+ * 记录项目采用 kse 时的配置选择
+ */
+class AdoptionConfig {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.configPath = path.join(projectPath, '.kiro', 'adoption-config.json');
+  }
+
+  /**
+   * 读取配置文件
+   * 
+   * @returns {Promise<Object|null>} 配置对象，如果不存在则返回 null
+   */
+  async read() {
+    try {
+      const exists = await fs.pathExists(this.configPath);
+      if (!exists) {
+        return null;
+      }
+
+      const content = await fs.readFile(this.configPath, 'utf8');
+      return JSON.parse(content);
+    } catch (error) {
+      console.error(`Error reading adoption config: ${error.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * 写入配置文件
+   * 
+   * @param {Object} config - 配置对象
+   * @returns {Promise<boolean>} 是否成功
+   */
+  async write(config) {
+    try {
+      // 确保目录存在
+      await fs.ensureDir(path.dirname(this.configPath));
+
+      // 写入配置
+      await fs.writeFile(
+        this.configPath,
+        JSON.stringify(config, null, 2),
+        'utf8'
+      );
+
+      return true;
+    } catch (error) {
+      console.error(`Error writing adoption config: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * 更新 steering 策略配置
+   * 
+   * @param {string} strategy - 策略 ('use-kse' | 'use-project')
+   * @param {string|null} backupId - 备份 ID（如果有）
+   * @returns {Promise<boolean>} 是否成功
+   */
+  async updateSteeringStrategy(strategy, backupId = null) {
+    // 读取现有配置
+    let config = await this.read();
+
+    if (!config) {
+      // 创建新配置
+      config = {
+        version: '1.0.0',
+        adoptedAt: new Date().toISOString(),
+        multiUserMode: false
+      };
+    }
+
+    // 更新 steering 策略
+    config.steeringStrategy = strategy;
+    
+    if (backupId) {
+      config.steeringBackupId = backupId;
+    }
+
+    config.lastUpdated = new Date().toISOString();
+
+    // 写入配置
+    return await this.write(config);
+  }
+
+  /**
+   * 更新多用户模式配置
+   * 
+   * @param {boolean} enabled - 是否启用多用户模式
+   * @returns {Promise<boolean>} 是否成功
+   */
+  async updateMultiUserMode(enabled) {
+    let config = await this.read();
+
+    if (!config) {
+      config = {
+        version: '1.0.0',
+        adoptedAt: new Date().toISOString()
+      };
+    }
+
+    config.multiUserMode = enabled;
+    config.lastUpdated = new Date().toISOString();
+
+    return await this.write(config);
+  }
+
+  /**
+   * 获取 steering 策略
+   * 
+   * @returns {Promise<string|null>} 策略或 null
+   */
+  async getSteeringStrategy() {
+    const config = await this.read();
+    return config ? config.steeringStrategy : null;
+  }
+
+  /**
+   * 获取 steering 备份 ID
+   * 
+   * @returns {Promise<string|null>} 备份 ID 或 null
+   */
+  async getSteeringBackupId() {
+    const config = await this.read();
+    return config ? config.steeringBackupId : null;
+  }
+
+  /**
+   * 检查是否启用多用户模式
+   * 
+   * @returns {Promise<boolean>} 是否启用
+   */
+  async isMultiUserMode() {
+    const config = await this.read();
+    return config ? (config.multiUserMode || false) : false;
+  }
+
+  /**
+   * 创建初始配置
+   * 
+   * @param {Object} options - 配置选项
+   * @returns {Promise<boolean>} 是否成功
+   */
+  async initialize(options = {}) {
+    const config = {
+      version: '1.0.0',
+      adoptedAt: new Date().toISOString(),
+      steeringStrategy: options.steeringStrategy || 'use-kse',
+      multiUserMode: options.multiUserMode || false,
+      ...options
+    };
+
+    return await this.write(config);
+  }
+}
+
+module.exports = AdoptionConfig;

package/lib/steering/compliance-auto-fixer.js

@@ -0,0 +1,204 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Automatically fix steering directory compliance violations
+ * by backing up and removing disallowed files and subdirectories
+ */
+class ComplianceAutoFixer {
+  /**
+   * Fix compliance violations automatically (no user confirmation)
+   * @param {string} steeringPath - Path to steering directory
+   * @param {Array} violations - List of violations from compliance check
+   * @returns {Object} Fix result with backup info and cleaned files
+   */
+  async fix(steeringPath, violations) {
+    if (!violations || violations.length === 0) {
+      return {
+        success: true,
+        message: 'No violations to fix',
+        backupPath: null,
+        cleanedFiles: [],
+        cleanedDirs: []
+      };
+    }
+
+    // Separate violations by type
+    const disallowedFiles = violations
+      .filter(v => v.type === 'disallowed_file')
+      .map(v => v.name);
+    const subdirectories = violations
+      .filter(v => v.type === 'subdirectory')
+      .map(v => v.name);
+
+    // Check if this is a multi-user project (contexts/ directory exists)
+    const contextsPath = path.join(path.dirname(path.dirname(steeringPath)), 'contexts');
+    const isMultiUser = await fs.pathExists(contextsPath);
+
+    // Show what will be fixed
+    console.log(chalk.yellow('\n🔧 Auto-fixing steering directory compliance violations...\n'));
+    
+    if (disallowedFiles.length > 0) {
+      console.log(chalk.yellow('Disallowed files to be removed:'));
+      disallowedFiles.forEach(file => console.log(`  - ${file}`));
+      console.log();
+    }
+    
+    if (subdirectories.length > 0) {
+      console.log(chalk.yellow('Subdirectories to be removed:'));
+      subdirectories.forEach(dir => console.log(`  - ${dir}/`));
+      console.log();
+    }
+
+    // Show multi-user warning if applicable
+    if (isMultiUser) {
+      console.log(chalk.blue('ℹ️  Multi-user project detected'));
+      console.log(chalk.blue('   Your personal CURRENT_CONTEXT.md is preserved in contexts/'));
+      console.log();
+    }
+
+    // Create backup
+    const backupPath = await this._createBackup(steeringPath, disallowedFiles, subdirectories);
+    console.log(chalk.green(`✓ Backup created: ${backupPath}\n`));
+
+    // Clean up violations
+    const cleanedFiles = [];
+    const cleanedDirs = [];
+
+    // Remove disallowed files
+    for (const file of disallowedFiles) {
+      const filePath = path.join(steeringPath, file);
+      try {
+        await fs.remove(filePath);
+        cleanedFiles.push(file);
+        console.log(chalk.green(`✓ Removed file: ${file}`));
+      } catch (error) {
+        console.error(chalk.red(`✗ Failed to remove ${file}: ${error.message}`));
+      }
+    }
+
+    // Remove subdirectories
+    for (const dir of subdirectories) {
+      const dirPath = path.join(steeringPath, dir);
+      try {
+        await fs.remove(dirPath);
+        cleanedDirs.push(dir);
+        console.log(chalk.green(`✓ Removed directory: ${dir}/`));
+      } catch (error) {
+        console.error(chalk.red(`✗ Failed to remove ${dir}/: ${error.message}`));
+      }
+    }
+
+    console.log(chalk.green('\n✓ Steering directory cleaned successfully!\n'));
+    console.log(chalk.blue('Backup location:'));
+    console.log(`  ${backupPath}\n`);
+    console.log(chalk.blue('To restore from backup:'));
+    console.log(`  kse rollback --backup ${path.basename(backupPath)}\n`);
+
+    return {
+      success: true,
+      message: 'Steering directory fixed successfully',
+      backupPath,
+      cleanedFiles,
+      cleanedDirs
+    };
+  }
+
+  /**
+   * Create differential backup of violations only
+   * @private
+   */
+  async _createBackup(steeringPath, files, dirs) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+    const backupId = `steering-cleanup-${timestamp}`;
+    const backupPath = path.join(path.dirname(path.dirname(steeringPath)), 'backups', backupId);
+
+    // Create backup directory
+    await fs.ensureDir(backupPath);
+
+    // Backup disallowed files
+    for (const file of files) {
+      const sourcePath = path.join(steeringPath, file);
+      const destPath = path.join(backupPath, file);
+      
+      if (await fs.pathExists(sourcePath)) {
+        await fs.copy(sourcePath, destPath);
+      }
+    }
+
+    // Backup subdirectories
+    for (const dir of dirs) {
+      const sourcePath = path.join(steeringPath, dir);
+      const destPath = path.join(backupPath, dir);
+      
+      if (await fs.pathExists(sourcePath)) {
+        await fs.copy(sourcePath, destPath);
+      }
+    }
+
+    // Create backup manifest
+    const manifest = {
+      backupId,
+      timestamp: new Date().toISOString(),
+      type: 'steering-cleanup',
+      steeringPath,
+      files,
+      directories: dirs,
+      totalItems: files.length + dirs.length
+    };
+
+    await fs.writeJson(path.join(backupPath, 'manifest.json'), manifest, { spaces: 2 });
+
+    return backupPath;
+  }
+
+  /**
+   * Restore from backup
+   * @param {string} backupPath - Path to backup directory
+   * @param {string} steeringPath - Path to steering directory
+   */
+  async restore(backupPath, steeringPath) {
+    // Read manifest
+    const manifestPath = path.join(backupPath, 'manifest.json');
+    if (!await fs.pathExists(manifestPath)) {
+      throw new Error('Invalid backup: manifest.json not found');
+    }
+
+    const manifest = await fs.readJson(manifestPath);
+
+    console.log(chalk.yellow('\n🔄 Restoring from backup...\n'));
+
+    // Restore files
+    for (const file of manifest.files) {
+      const sourcePath = path.join(backupPath, file);
+      const destPath = path.join(steeringPath, file);
+      
+      if (await fs.pathExists(sourcePath)) {
+        await fs.copy(sourcePath, destPath);
+        console.log(chalk.green(`✓ Restored file: ${file}`));
+      }
+    }
+
+    // Restore directories
+    for (const dir of manifest.directories) {
+      const sourcePath = path.join(backupPath, dir);
+      const destPath = path.join(steeringPath, dir);
+      
+      if (await fs.pathExists(sourcePath)) {
+        await fs.copy(sourcePath, destPath);
+        console.log(chalk.green(`✓ Restored directory: ${dir}/`));
+      }
+    }
+
+    console.log(chalk.green('\n✓ Restore completed!\n'));
+
+    return {
+      success: true,
+      restoredFiles: manifest.files,
+      restoredDirs: manifest.directories
+    };
+  }
+}
+
+module.exports = ComplianceAutoFixer;

package/lib/steering/compliance-cache.js

@@ -0,0 +1,99 @@
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+
+/**
+ * ComplianceCache - Manages version-based check caching
+ * 
+ * Stores the last successful compliance check version to avoid
+ * repeated checks for the same kse version.
+ */
+class ComplianceCache {
+  /**
+   * Create a new ComplianceCache instance
+   * 
+   * @param {string} cachePath - Optional custom cache file path
+   */
+  constructor(cachePath = null) {
+    this.cachePath = cachePath || this.getDefaultCachePath();
+  }
+
+  /**
+   * Get the default cache file path
+   * 
+   * @returns {string} Path to ~/.kse/steering-check-cache.json
+   */
+  getDefaultCachePath() {
+    const homeDir = os.homedir();
+    return path.join(homeDir, '.kse', 'steering-check-cache.json');
+  }
+
+  /**
+   * Check if cache is valid for current version
+   * 
+   * @param {string} currentVersion - Current kse version
+   * @returns {boolean} True if cache is valid
+   */
+  isValid(currentVersion) {
+    try {
+      if (!fs.existsSync(this.cachePath)) {
+        return false;
+      }
+
+      const cache = JSON.parse(fs.readFileSync(this.cachePath, 'utf8'));
+      return cache.version === currentVersion && cache.lastCheck === 'success';
+    } catch (error) {
+      // Treat any cache read error as cache miss
+      return false;
+    }
+  }
+
+  /**
+   * Update cache with successful check
+   * 
+   * @param {string} version - kse version
+   * @returns {boolean} True if update succeeded
+   */
+  update(version) {
+    try {
+      const cacheDir = path.dirname(this.cachePath);
+      
+      // Ensure cache directory exists
+      if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+      }
+
+      const cacheData = {
+        version,
+        timestamp: new Date().toISOString(),
+        lastCheck: 'success'
+      };
+
+      fs.writeFileSync(this.cachePath, JSON.stringify(cacheData, null, 2), 'utf8');
+      return true;
+    } catch (error) {
+      // Log error but don't throw - cache write failure is not critical
+      console.warn(`Warning: Failed to update compliance cache: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Clear the cache
+   * 
+   * @returns {boolean} True if clear succeeded
+   */
+  clear() {
+    try {
+      if (fs.existsSync(this.cachePath)) {
+        fs.unlinkSync(this.cachePath);
+      }
+      return true;
+    } catch (error) {
+      console.warn(`Warning: Failed to clear compliance cache: ${error.message}`);
+      return false;
+    }
+  }
+}
+
+module.exports = ComplianceCache;