scene-capability-engine 3.0.0

package/lib/gitignore/gitignore-integration.js

@@ -0,0 +1,267 @@
+/**
+ * GitignoreIntegration - Integrates .gitignore auto-fix with adopt/upgrade flows
+ * 
+ * Coordinates detection, backup, transformation, and reporting for .gitignore fixes.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const GitignoreDetector = require('./gitignore-detector');
+const GitignoreTransformer = require('./gitignore-transformer');
+const GitignoreBackup = require('./gitignore-backup');
+
+/**
+ * @typedef {Object} GitignoreFixResult
+ * @property {boolean} success - Fix succeeded
+ * @property {string} action - 'created' | 'updated' | 'skipped'
+ * @property {string} backupId - Backup ID (if created)
+ * @property {string[]} added - Rules added
+ * @property {string[]} removed - Rules removed
+ * @property {string} message - User-friendly message
+ */
+
+class GitignoreIntegration {
+  constructor(dependencies = {}) {
+    this.detector = dependencies.detector || new GitignoreDetector();
+    this.transformer = dependencies.transformer || new GitignoreTransformer();
+    this.backup = dependencies.backup || new GitignoreBackup();
+  }
+
+  /**
+   * Runs .gitignore check and fix
+   * 
+   * @param {string} projectPath - Project root path
+   * @param {Object} options - Integration options
+   * @param {boolean} options.skipBackup - Skip backup creation (dangerous)
+   * @param {boolean} options.dryRun - Preview without executing
+   * @returns {Promise<GitignoreFixResult>}
+   */
+  async checkAndFix(projectPath, options = {}) {
+    const { skipBackup = false, dryRun = false } = options;
+    
+    try {
+      // Stage 1: Detect .gitignore status
+      const status = await this.detector.analyzeGitignore(projectPath);
+      
+      // If compliant, no action needed
+      if (status.strategy === 'skip') {
+        return {
+          success: true,
+          action: 'skipped',
+          backupId: null,
+          added: [],
+          removed: [],
+          message: '.gitignore already optimal'
+        };
+      }
+      
+      // Stage 2: Transform content
+      const transformResult = this.transformer.transform(status.content, status);
+      
+      // Dry run mode - stop here
+      if (dryRun) {
+        return {
+          success: true,
+          action: status.strategy === 'add' ? 'would-create' : 'would-update',
+          backupId: null,
+          added: transformResult.added,
+          removed: transformResult.removed,
+          message: 'Dry run - no changes made'
+        };
+      }
+      
+      // Stage 3: Create backup (if file exists and not skipped)
+      let backupId = null;
+      if (status.exists && !skipBackup) {
+        const backupInfo = await this.backup.createBackup(projectPath);
+        backupId = backupInfo.id;
+      }
+      
+      // Stage 4: Write new .gitignore
+      const gitignorePath = path.join(projectPath, '.gitignore');
+      await fs.writeFile(gitignorePath, transformResult.content, 'utf8');
+      
+      // Stage 5: Return result
+      return {
+        success: true,
+        action: status.strategy === 'add' ? 'created' : 'updated',
+        backupId,
+        added: transformResult.added,
+        removed: transformResult.removed,
+        message: this.generateSuccessMessage(status, backupId)
+      };
+      
+    } catch (error) {
+      return {
+        success: false,
+        action: 'failed',
+        backupId: null,
+        added: [],
+        removed: [],
+        message: `Failed to fix .gitignore: ${error.message}`
+      };
+    }
+  }
+
+  /**
+   * Integrates with adoption flow
+   * 
+   * @param {string} projectPath - Project root path
+   * @returns {Promise<GitignoreFixResult>}
+   */
+  async integrateWithAdopt(projectPath) {
+    return await this.checkAndFix(projectPath);
+  }
+
+  /**
+   * Integrates with upgrade flow
+   * 
+   * @param {string} projectPath - Project root path
+   * @returns {Promise<GitignoreFixResult>}
+   */
+  async integrateWithUpgrade(projectPath) {
+    return await this.checkAndFix(projectPath);
+  }
+
+  /**
+   * Standalone doctor command
+   * 
+   * @param {string} projectPath - Project root path
+   * @returns {Promise<GitignoreFixResult>}
+   */
+  async runDoctor(projectPath) {
+    console.log(chalk.blue('🔍 Checking .gitignore configuration...'));
+    console.log();
+    
+    const result = await this.checkAndFix(projectPath);
+    
+    // Display detailed result
+    this.displayDoctorResult(result);
+    
+    return result;
+  }
+
+  /**
+   * Generates success message
+   * 
+   * @param {Object} status - Detection status
+   * @param {string} backupId - Backup ID
+   * @returns {string}
+   */
+  generateSuccessMessage(status, backupId) {
+    if (status.strategy === 'add') {
+      return '.gitignore created with layered strategy';
+    } else if (status.strategy === 'update') {
+      return `.gitignore updated for team collaboration${backupId ? ` (backup: ${backupId})` : ''}`;
+    }
+    return '.gitignore already optimal';
+  }
+
+  /**
+   * Displays doctor command result
+   * 
+   * @param {GitignoreFixResult} result - Fix result
+   */
+  displayDoctorResult(result) {
+    if (result.action === 'skipped') {
+      console.log(chalk.green('✅ .gitignore is already optimal'));
+      console.log();
+      console.log(chalk.gray('  Current strategy: Layered .kiro/ management'));
+      console.log(chalk.gray('  - Specs are committable'));
+      console.log(chalk.gray('  - Personal state is excluded'));
+      console.log();
+      return;
+    }
+    
+    if (!result.success) {
+      console.log(chalk.red('❌ Failed to fix .gitignore'));
+      console.log();
+      console.log(chalk.red(`  ${result.message}`));
+      console.log();
+      return;
+    }
+    
+    console.log(chalk.green(`✅ .gitignore ${result.action}`));
+    console.log();
+    
+    if (result.backupId) {
+      console.log(chalk.blue('📦 Backup created:'), result.backupId);
+      console.log(chalk.gray('  Location:'), `.kiro/backups/${result.backupId}`);
+      console.log();
+    }
+    
+    if (result.removed.length > 0) {
+      console.log(chalk.yellow('Removed old patterns:'));
+      result.removed.forEach(pattern => {
+        console.log(chalk.red(`  - ${pattern}`));
+      });
+      console.log();
+    }
+    
+    if (result.added.length > 0) {
+      console.log(chalk.green('Added layered rules:'));
+      console.log(chalk.gray(`  + ${result.added.length} exclusion rules`));
+      console.log();
+    }
+    
+    console.log(chalk.blue('💡 What this means:'));
+    console.log('  ✅ Spec documents are now committable');
+    console.log('  ✅ Team can see requirements, design, and tasks');
+    console.log('  ✅ Personal state is excluded (no merge conflicts)');
+    console.log();
+    
+    console.log(chalk.gray('  Learn more:'), chalk.cyan('docs/team-collaboration-guide.md'));
+    
+    if (result.backupId) {
+      console.log();
+      console.log(chalk.gray('  To rollback:'), chalk.cyan(`kse doctor --restore-gitignore ${result.backupId}`));
+    }
+    
+    console.log();
+  }
+
+  /**
+   * Displays integration result (for adopt/upgrade flows)
+   * 
+   * @param {GitignoreFixResult} result - Fix result
+   */
+  displayIntegrationResult(result) {
+    if (result.action === 'skipped') {
+      return; // No output for compliant .gitignore
+    }
+    
+    if (!result.success) {
+      console.log(chalk.yellow('⚠️  .gitignore fix failed:'), result.message);
+      console.log(chalk.gray('  Run'), chalk.cyan('kse doctor --fix-gitignore'), chalk.gray('to fix manually'));
+      return;
+    }
+    
+    console.log(chalk.blue('📝 .gitignore updated for team collaboration'));
+    
+    if (result.backupId) {
+      console.log(chalk.gray('  Backup:'), result.backupId);
+    }
+    
+    if (result.removed.length > 0) {
+      console.log(chalk.gray('  Changes:'));
+      console.log(chalk.yellow(`    - Removed ${result.removed.length} old pattern(s)`));
+    }
+    
+    console.log(chalk.green('    + Added layered .kiro/ exclusion rules'));
+    console.log(chalk.green('    + Specs are now committable'));
+    console.log(chalk.green('    + Personal state is excluded'));
+    console.log();
+    
+    console.log(chalk.blue('💡 Why this matters:'));
+    console.log('  - Team can see Spec documents (requirements, design, tasks)');
+    console.log('  - No merge conflicts on personal state');
+    console.log('  - Follows best practices for team collaboration');
+    console.log();
+    
+    console.log(chalk.gray('  Learn more:'), chalk.cyan('docs/team-collaboration-guide.md'));
+    console.log();
+  }
+}
+
+module.exports = GitignoreIntegration;

package/lib/gitignore/gitignore-transformer.js

@@ -0,0 +1,193 @@
+/**
+ * GitignoreTransformer - Transforms .gitignore to use layered strategy
+ * 
+ * Removes old blanket exclusion patterns and adds layered exclusion rules
+ * while preserving user customizations.
+ */
+
+const LAYERED_RULES_TEMPLATE = require('./layered-rules-template');
+
+/**
+ * @typedef {Object} TransformResult
+ * @property {string} content - New .gitignore content
+ * @property {string[]} added - Rules added
+ * @property {string[]} removed - Rules removed
+ * @property {string[]} preserved - User rules preserved
+ */
+
+class GitignoreTransformer {
+  constructor() {
+    // Old patterns to remove
+    this.OLD_PATTERNS = [
+      /^\.kiro\/?\s*$/,
+      /^\.kiro\/\*\s*$/,
+      /^\.kiro\/\*\*\s*$/
+    ];
+  }
+
+  /**
+   * Applies layered strategy to .gitignore
+   * 
+   * @param {string} currentContent - Current .gitignore content (or empty)
+   * @param {Object} status - Detection status
+   * @returns {TransformResult}
+   */
+  transform(currentContent, status) {
+    const result = {
+      content: '',
+      added: [],
+      removed: [],
+      preserved: []
+    };
+    
+    if (status.strategy === 'skip') {
+      // Already compliant, no changes needed
+      result.content = currentContent;
+      return result;
+    }
+    
+    if (status.strategy === 'add') {
+      // Missing .gitignore, create new one
+      result.content = LAYERED_RULES_TEMPLATE;
+      result.added = this.extractRulePatterns(LAYERED_RULES_TEMPLATE);
+      return result;
+    }
+    
+    if (status.strategy === 'update') {
+      // Remove old patterns and add layered rules
+      const cleaned = this.removeOldPatterns(currentContent, result);
+      result.content = this.addLayeredRules(cleaned);
+      result.added = this.extractRulePatterns(LAYERED_RULES_TEMPLATE);
+      
+      // Track preserved rules
+      const lines = currentContent.split(/\r?\n/);
+      lines.forEach(line => {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith('#') && !this.isOldPattern(trimmed)) {
+          if (!trimmed.includes('.kiro')) {
+            result.preserved.push(trimmed);
+          }
+        }
+      });
+    }
+    
+    return result;
+  }
+
+  /**
+   * Removes old blanket exclusion patterns
+   * 
+   * @param {string} content - .gitignore content
+   * @param {TransformResult} result - Result object to track removed patterns
+   * @returns {string} - Content with old patterns removed
+   */
+  removeOldPatterns(content, result) {
+    // Detect line ending style
+    const lineEnding = content.includes('\r\n') ? '\r\n' : '\n';
+    
+    const lines = content.split(/\r?\n/);
+    const filtered = [];
+    let inManagedSection = false;
+    
+    for (const line of lines) {
+      const trimmed = line.trim();
+      
+      // Track kse-managed section
+      if (trimmed.includes('kse - DO NOT EDIT THIS SECTION')) {
+        inManagedSection = true;
+        continue; // Skip managed section start
+      } else if (trimmed.includes('End of kse-managed section')) {
+        inManagedSection = false;
+        continue; // Skip managed section end
+      }
+      
+      // Skip lines in managed section
+      if (inManagedSection) {
+        continue;
+      }
+      
+      // Check if line is old pattern
+      if (this.isOldPattern(trimmed)) {
+        result.removed.push(trimmed);
+        continue; // Skip old pattern
+      }
+      
+      // Preserve line
+      filtered.push(line);
+    }
+    
+    return filtered.join(lineEnding);
+  }
+
+  /**
+   * Checks if pattern is an old blanket exclusion
+   * 
+   * @param {string} pattern - Pattern to check
+   * @returns {boolean}
+   */
+  isOldPattern(pattern) {
+    for (const regex of this.OLD_PATTERNS) {
+      if (regex.test(pattern)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Adds layered exclusion rules
+   * 
+   * @param {string} content - .gitignore content
+   * @returns {string} - Content with layered rules added
+   */
+  addLayeredRules(content) {
+    // Detect line ending style from existing content
+    const lineEnding = content.includes('\r\n') ? '\r\n' : '\n';
+    
+    // Ensure content ends with newline
+    let result = content.trim();
+    
+    if (result) {
+      result += lineEnding + lineEnding;
+    }
+    
+    // Convert template to match line ending style
+    const template = LAYERED_RULES_TEMPLATE.replace(/\n/g, lineEnding);
+    
+    // Add layered rules section
+    result += template;
+    
+    return result;
+  }
+
+  /**
+   * Generates layered rules section
+   * 
+   * @returns {string}
+   */
+  generateLayeredSection() {
+    return LAYERED_RULES_TEMPLATE;
+  }
+
+  /**
+   * Extracts rule patterns from template (for reporting)
+   * 
+   * @param {string} template - Template content
+   * @returns {string[]} - Rule patterns
+   */
+  extractRulePatterns(template) {
+    const lines = template.split(/\r?\n/);
+    const patterns = [];
+    
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('=')) {
+        patterns.push(trimmed);
+      }
+    }
+    
+    return patterns;
+  }
+}
+
+module.exports = GitignoreTransformer;

package/lib/gitignore/layered-rules-template.js

@@ -0,0 +1,42 @@
+/**
+ * Layered .gitignore rules template
+ * 
+ * This template defines the layered strategy for .kiro/ directory:
+ * - Commit Specs and shared content
+ * - Exclude personal state and temporary files
+ */
+
+const LAYERED_RULES_TEMPLATE = `# ========================================
+# .kiro/ Directory - Layered Management
+# ========================================
+# Generated by kse - DO NOT EDIT THIS SECTION
+# See: docs/team-collaboration-guide.md
+
+# Personal state files (DO NOT commit)
+.kiro/steering/CURRENT_CONTEXT.md
+.kiro/contexts/.active
+.kiro/contexts/*/CURRENT_CONTEXT.md
+
+# Environment configuration (DO NOT commit)
+.kiro/environments.json
+.kiro/env-backups/
+
+# Temporary files and backups (DO NOT commit)
+.kiro/backups/
+.kiro/logs/
+.kiro/reports/
+
+# Spec artifacts (COMMIT - but exclude temporary files)
+.kiro/specs/**/SESSION-*.md
+.kiro/specs/**/*-SUMMARY.md
+.kiro/specs/**/*-COMPLETE.md
+.kiro/specs/**/TEMP-*.md
+.kiro/specs/**/WIP-*.md
+.kiro/specs/**/MVP-*.md
+
+# ========================================
+# End of kse-managed section
+# ========================================
+`;
+
+module.exports = LAYERED_RULES_TEMPLATE;