scene-capability-engine 3.0.0

package/lib/gitignore/gitignore-backup.js

@@ -0,0 +1,229 @@
+/**
+ * GitignoreBackup - Creates backups before modifying .gitignore
+ * 
+ * Provides backup creation, restoration, and management functionality
+ * with automatic cleanup of old backups.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * @typedef {Object} BackupInfo
+ * @property {string} id - Backup ID (e.g., 'gitignore-2026-01-30-143022')
+ * @property {string} created - ISO timestamp
+ * @property {string} path - Backup file path
+ * @property {number} size - File size in bytes
+ */
+
+/**
+ * @typedef {Object} RestoreResult
+ * @property {boolean} success - Restoration succeeded
+ * @property {string} message - Result message
+ */
+
+class GitignoreBackup {
+  constructor() {
+    this.MAX_BACKUPS = 10;
+  }
+
+  /**
+   * Creates backup of .gitignore
+   * 
+   * @param {string} projectPath - Project root path
+   * @returns {Promise<BackupInfo>}
+   */
+  async createBackup(projectPath) {
+    const gitignorePath = path.join(projectPath, '.gitignore');
+    
+    // Check if .gitignore exists
+    if (!await fs.pathExists(gitignorePath)) {
+      throw new Error('.gitignore file does not exist');
+    }
+    
+    // Read .gitignore content
+    const content = await fs.readFile(gitignorePath, 'utf8');
+    const stats = await fs.stat(gitignorePath);
+    
+    // Generate backup ID with timestamp
+    const timestamp = this.generateTimestamp();
+    const backupId = `gitignore-${timestamp}`;
+    
+    // Create backup directory
+    const backupDir = path.join(projectPath, '.kiro', 'backups');
+    await fs.ensureDir(backupDir);
+    
+    // Write backup file
+    const backupPath = path.join(backupDir, backupId);
+    await fs.writeFile(backupPath, content, 'utf8');
+    
+    // Create metadata
+    const checksum = this.calculateChecksum(content);
+    const metadata = {
+      id: backupId,
+      created: new Date().toISOString(),
+      originalPath: '.gitignore',
+      size: stats.size,
+      checksum
+    };
+    
+    const metaPath = path.join(backupDir, `${backupId}.meta.json`);
+    await fs.writeFile(metaPath, JSON.stringify(metadata, null, 2), 'utf8');
+    
+    // Cleanup old backups
+    await this.cleanupOldBackups(projectPath);
+    
+    return {
+      id: backupId,
+      created: metadata.created,
+      path: backupPath,
+      size: stats.size
+    };
+  }
+
+  /**
+   * Restores .gitignore from backup
+   * 
+   * @param {string} projectPath - Project root path
+   * @param {string} backupId - Backup ID
+   * @returns {Promise<RestoreResult>}
+   */
+  async restore(projectPath, backupId) {
+    const backupDir = path.join(projectPath, '.kiro', 'backups');
+    const backupPath = path.join(backupDir, backupId);
+    const metaPath = path.join(backupDir, `${backupId}.meta.json`);
+    
+    // Check if backup exists
+    if (!await fs.pathExists(backupPath)) {
+      return {
+        success: false,
+        message: `Backup not found: ${backupId}`
+      };
+    }
+    
+    // Read backup content
+    const content = await fs.readFile(backupPath, 'utf8');
+    
+    // Verify checksum if metadata exists
+    if (await fs.pathExists(metaPath)) {
+      const metadata = await fs.readJson(metaPath);
+      const checksum = this.calculateChecksum(content);
+      
+      if (checksum !== metadata.checksum) {
+        return {
+          success: false,
+          message: 'Backup file is corrupted (checksum mismatch)'
+        };
+      }
+    }
+    
+    // Restore to original location
+    const gitignorePath = path.join(projectPath, '.gitignore');
+    await fs.writeFile(gitignorePath, content, 'utf8');
+    
+    return {
+      success: true,
+      message: `Successfully restored .gitignore from backup: ${backupId}`
+    };
+  }
+
+  /**
+   * Lists available .gitignore backups
+   * 
+   * @param {string} projectPath - Project root path
+   * @returns {Promise<BackupInfo[]>}
+   */
+  async listBackups(projectPath) {
+    const backupDir = path.join(projectPath, '.kiro', 'backups');
+    
+    if (!await fs.pathExists(backupDir)) {
+      return [];
+    }
+    
+    const files = await fs.readdir(backupDir);
+    const backups = [];
+    
+    for (const file of files) {
+      if (file.startsWith('gitignore-') && !file.endsWith('.meta.json')) {
+        const backupPath = path.join(backupDir, file);
+        const metaPath = path.join(backupDir, `${file}.meta.json`);
+        
+        let metadata = null;
+        if (await fs.pathExists(metaPath)) {
+          metadata = await fs.readJson(metaPath);
+        }
+        
+        const stats = await fs.stat(backupPath);
+        
+        backups.push({
+          id: file,
+          created: metadata ? metadata.created : stats.mtime.toISOString(),
+          path: backupPath,
+          size: stats.size
+        });
+      }
+    }
+    
+    // Sort by creation time (newest first)
+    backups.sort((a, b) => new Date(b.created) - new Date(a.created));
+    
+    return backups;
+  }
+
+  /**
+   * Cleans up old backups (keep last 10)
+   * 
+   * @param {string} projectPath - Project root path
+   * @returns {Promise<void>}
+   */
+  async cleanupOldBackups(projectPath) {
+    const backups = await this.listBackups(projectPath);
+    
+    if (backups.length <= this.MAX_BACKUPS) {
+      return;
+    }
+    
+    // Remove oldest backups
+    const toRemove = backups.slice(this.MAX_BACKUPS);
+    
+    for (const backup of toRemove) {
+      await fs.remove(backup.path);
+      
+      // Remove metadata if exists
+      const metaPath = `${backup.path}.meta.json`;
+      if (await fs.pathExists(metaPath)) {
+        await fs.remove(metaPath);
+      }
+    }
+  }
+
+  /**
+   * Generates timestamp for backup ID
+   * 
+   * @returns {string} - Timestamp in format YYYY-MM-DD-HHMMSS
+   */
+  generateTimestamp() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    const hours = String(now.getHours()).padStart(2, '0');
+    const minutes = String(now.getMinutes()).padStart(2, '0');
+    const seconds = String(now.getSeconds()).padStart(2, '0');
+    
+    return `${year}-${month}-${day}-${hours}${minutes}${seconds}`;
+  }
+
+  /**
+   * Calculates SHA-256 checksum of content
+   * 
+   * @param {string} content - Content to hash
+   * @returns {string} - Hex checksum
+   */
+  calculateChecksum(content) {
+    return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+  }
+}
+
+module.exports = GitignoreBackup;

package/lib/gitignore/gitignore-detector.js

@@ -0,0 +1,239 @@
+/**
+ * GitignoreDetector - Analyzes .gitignore status
+ * 
+ * Detects .gitignore file existence, parses content, identifies old patterns,
+ * and determines the appropriate fix strategy.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * @typedef {Object} GitignoreRule
+ * @property {string} pattern - Rule pattern (e.g., '.kiro/backups/')
+ * @property {string} type - 'exclusion' | 'negation' | 'comment'
+ * @property {number} line - Line number in file
+ * @property {boolean} isKiroRelated - Rule relates to .kiro/
+ * @property {boolean} isManaged - Rule is in kse-managed section
+ */
+
+/**
+ * @typedef {Object} GitignoreStatus
+ * @property {boolean} exists - .gitignore file exists
+ * @property {string} status - 'missing' | 'old-pattern' | 'incomplete' | 'compliant'
+ * @property {string} strategy - 'add' | 'update' | 'skip'
+ * @property {string[]} oldPatterns - Old patterns found
+ * @property {string[]} missingRules - Missing layered rules
+ * @property {string} content - Current .gitignore content
+ */
+
+class GitignoreDetector {
+  constructor() {
+    // Old patterns that indicate blanket exclusion
+    this.OLD_PATTERNS = [
+      /^\.kiro\/?\s*$/,           // .kiro/ or .kiro
+      /^\.kiro\/\*\s*$/,          // .kiro/*
+      /^\.kiro\/\*\*\s*$/         // .kiro/**
+    ];
+    
+    // Required layered rules (key patterns to check)
+    this.REQUIRED_RULES = [
+      '.kiro/steering/CURRENT_CONTEXT.md',
+      '.kiro/contexts/.active',
+      '.kiro/environments.json',
+      '.kiro/backups/',
+      '.kiro/logs/',
+      '.kiro/reports/'
+    ];
+  }
+
+  /**
+   * Analyzes .gitignore status
+   * 
+   * @param {string} projectPath - Project root path
+   * @returns {Promise<GitignoreStatus>}
+   */
+  async analyzeGitignore(projectPath) {
+    const gitignorePath = path.join(projectPath, '.gitignore');
+    
+    // Check if .gitignore exists
+    const fileExists = await this.exists(projectPath);
+    
+    if (!fileExists) {
+      return {
+        exists: false,
+        status: 'missing',
+        strategy: 'add',
+        oldPatterns: [],
+        missingRules: [...this.REQUIRED_RULES],
+        content: ''
+      };
+    }
+    
+    // Read and parse .gitignore
+    const content = await fs.readFile(gitignorePath, 'utf8');
+    const rules = this.parseGitignore(content);
+    
+    // Check for old patterns
+    const oldPatterns = this.findOldPatterns(rules);
+    const hasOld = oldPatterns.length > 0;
+    
+    // Check for layered strategy
+    const missingRules = this.findMissingRules(rules);
+    const hasLayered = missingRules.length === 0;
+    
+    // Determine status and strategy
+    let status, strategy;
+    
+    if (hasOld) {
+      status = 'old-pattern';
+      strategy = 'update';
+    } else if (!hasLayered) {
+      status = 'incomplete';
+      strategy = 'update';
+    } else {
+      status = 'compliant';
+      strategy = 'skip';
+    }
+    
+    return {
+      exists: true,
+      status,
+      strategy,
+      oldPatterns,
+      missingRules,
+      content
+    };
+  }
+
+  /**
+   * Checks if .gitignore exists
+   * 
+   * @param {string} projectPath - Project root path
+   * @returns {Promise<boolean>}
+   */
+  async exists(projectPath) {
+    const gitignorePath = path.join(projectPath, '.gitignore');
+    return await fs.pathExists(gitignorePath);
+  }
+
+  /**
+   * Parses .gitignore content into rules
+   * 
+   * @param {string} content - .gitignore file content
+   * @returns {GitignoreRule[]}
+   */
+  parseGitignore(content) {
+    const lines = content.split(/\r?\n/);
+    const rules = [];
+    let inManagedSection = false;
+    
+    lines.forEach((line, index) => {
+      const trimmed = line.trim();
+      
+      // Track kse-managed section
+      if (trimmed.includes('kse - DO NOT EDIT THIS SECTION')) {
+        inManagedSection = true;
+      } else if (trimmed.includes('End of kse-managed section')) {
+        inManagedSection = false;
+      }
+      
+      // Determine rule type
+      let type = 'exclusion';
+      let pattern = trimmed;
+      
+      if (trimmed.startsWith('#')) {
+        type = 'comment';
+      } else if (trimmed.startsWith('!')) {
+        type = 'negation';
+        pattern = trimmed.substring(1);
+      } else if (trimmed === '') {
+        return; // Skip blank lines
+      }
+      
+      // Check if .kiro-related
+      const isKiroRelated = pattern.includes('.kiro');
+      
+      rules.push({
+        pattern: trimmed,
+        type,
+        line: index + 1,
+        isKiroRelated,
+        isManaged: inManagedSection
+      });
+    });
+    
+    return rules;
+  }
+
+  /**
+   * Finds old blanket exclusion patterns
+   * 
+   * @param {GitignoreRule[]} rules - Parsed rules
+   * @returns {string[]} - Old patterns found
+   */
+  findOldPatterns(rules) {
+    const oldPatterns = [];
+    
+    for (const rule of rules) {
+      if (rule.type === 'exclusion' && rule.isKiroRelated) {
+        for (const pattern of this.OLD_PATTERNS) {
+          if (pattern.test(rule.pattern)) {
+            oldPatterns.push(rule.pattern);
+            break;
+          }
+        }
+      }
+    }
+    
+    return oldPatterns;
+  }
+
+  /**
+   * Finds missing layered rules
+   * 
+   * @param {GitignoreRule[]} rules - Parsed rules
+   * @returns {string[]} - Missing rules
+   */
+  findMissingRules(rules) {
+    const existingPatterns = rules
+      .filter(r => r.type === 'exclusion')
+      .map(r => r.pattern);
+    
+    const missing = [];
+    
+    for (const required of this.REQUIRED_RULES) {
+      const found = existingPatterns.some(pattern => 
+        pattern.includes(required) || required.includes(pattern)
+      );
+      
+      if (!found) {
+        missing.push(required);
+      }
+    }
+    
+    return missing;
+  }
+
+  /**
+   * Detects if .gitignore has old pattern
+   * 
+   * @param {GitignoreRule[]} rules - Parsed rules
+   * @returns {boolean}
+   */
+  hasOldPattern(rules) {
+    return this.findOldPatterns(rules).length > 0;
+  }
+
+  /**
+   * Checks if layered strategy is present
+   * 
+   * @param {GitignoreRule[]} rules - Parsed rules
+   * @returns {boolean}
+   */
+  hasLayeredStrategy(rules) {
+    return this.findMissingRules(rules).length === 0;
+  }
+}
+
+module.exports = GitignoreDetector;