scene-capability-engine 3.0.0

package/lib/repo/git-operations.js

@@ -0,0 +1,181 @@
+const simpleGit = require('simple-git');
+const GitError = require('./errors/git-error');
+
+/**
+ * GitOperations - Low-level Git operations wrapper around simple-git
+ * 
+ * Provides a clean interface for Git operations with consistent error handling
+ * and cross-platform compatibility.
+ */
+class GitOperations {
+  /**
+   * Create a simple-git instance for a repository
+   * @param {string} repoPath - Path to the Git repository
+   * @returns {SimpleGit} Configured simple-git instance
+   */
+  createGitInstance(repoPath) {
+    return simpleGit(repoPath);
+  }
+
+  /**
+   * Check if path is a valid Git repository
+   * @param {string} path - Path to check
+   * @returns {Promise<boolean>} True if path contains a valid Git repository
+   */
+  async isGitRepo(path) {
+    try {
+      const fs = require('fs').promises;
+      const pathModule = require('path');
+      
+      // Check if .git directory exists
+      const gitDir = pathModule.join(path, '.git');
+      const stats = await fs.stat(gitDir);
+      
+      // Verify it's a directory (not a file, which can occur in Git worktrees)
+      if (!stats.isDirectory()) {
+        return false;
+      }
+      
+      // Optional: Verify with git command for additional validation
+      // This ensures the .git directory is valid and not corrupted
+      try {
+        const git = this.createGitInstance(path);
+        await git.revparse(['--git-dir']);
+      } catch (gitError) {
+        // .git directory exists but git command failed
+        // Still treat as repository since .git directory is the authoritative indicator
+        // This handles cases like corrupted repos that still have .git structure
+      }
+      
+      return true;
+    } catch (error) {
+      // If we can't access .git directory (ENOENT, EACCES, etc.), it's not a repo
+      return false;
+    }
+  }
+
+  /**
+   * Get repository status
+   * @param {string} repoPath - Path to the Git repository
+   * @returns {Promise<StatusSummary>} Status summary from simple-git
+   * @throws {GitError} If status retrieval fails
+   */
+  async getStatus(repoPath) {
+    try {
+      const git = this.createGitInstance(repoPath);
+      return await git.status();
+    } catch (error) {
+      throw new GitError(
+        `Failed to get status for repository at ${repoPath}`,
+        'status',
+        null,
+        error.message
+      );
+    }
+  }
+
+  /**
+   * Get current branch name
+   * @param {string} repoPath - Path to the Git repository
+   * @returns {Promise<string>} Current branch name
+   * @throws {GitError} If branch retrieval fails
+   */
+  async getCurrentBranch(repoPath) {
+    try {
+      const git = this.createGitInstance(repoPath);
+      const status = await git.status();
+      return status.current;
+    } catch (error) {
+      throw new GitError(
+        `Failed to get current branch for repository at ${repoPath}`,
+        'branch',
+        null,
+        error.message
+      );
+    }
+  }
+
+  /**
+   * Get remote URL
+   * @param {string} repoPath - Path to the Git repository
+   * @param {string} remoteName - Name of the remote (default: 'origin')
+   * @returns {Promise<string|null>} Remote URL or null if remote doesn't exist
+   * @throws {GitError} If remote retrieval fails
+   */
+  async getRemoteUrl(repoPath, remoteName = 'origin') {
+    try {
+      const git = this.createGitInstance(repoPath);
+      const remotes = await git.getRemotes(true);
+      const remote = remotes.find(r => r.name === remoteName);
+      return remote ? remote.refs.fetch : null;
+    } catch (error) {
+      throw new GitError(
+        `Failed to get remote URL for ${remoteName} in repository at ${repoPath}`,
+        'remote',
+        null,
+        error.message
+      );
+    }
+  }
+
+  /**
+   * Get all remotes
+   * @param {string} repoPath - Path to the Git repository
+   * @returns {Promise<Array<{name: string, refs: {fetch: string, push: string}}>>} Array of remotes
+   * @throws {GitError} If remotes retrieval fails
+   */
+  async getRemotes(repoPath) {
+    try {
+      const git = this.createGitInstance(repoPath);
+      return await git.getRemotes(true);
+    } catch (error) {
+      throw new GitError(
+        `Failed to get remotes for repository at ${repoPath}`,
+        'remote',
+        null,
+        error.message
+      );
+    }
+  }
+
+  /**
+   * Check if remote is reachable
+   * @param {string} repoPath - Path to the Git repository
+   * @param {string} remoteName - Name of the remote (default: 'origin')
+   * @returns {Promise<boolean>} True if remote is reachable
+   */
+  async isRemoteReachable(repoPath, remoteName = 'origin') {
+    try {
+      const git = this.createGitInstance(repoPath);
+      // Use ls-remote to check if remote is reachable
+      await git.listRemote([remoteName]);
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Execute raw Git command
+   * @param {string} repoPath - Path to the Git repository
+   * @param {string[]} args - Git command arguments
+   * @returns {Promise<string>} Command output
+   * @throws {GitError} If command execution fails
+   */
+  async execRaw(repoPath, args) {
+    try {
+      const git = this.createGitInstance(repoPath);
+      const result = await git.raw(args);
+      return result;
+    } catch (error) {
+      throw new GitError(
+        `Failed to execute git command: git ${args.join(' ')}`,
+        `git ${args.join(' ')}`,
+        error.exitCode || null,
+        error.message
+      );
+    }
+  }
+}
+
+module.exports = GitOperations;

package/lib/repo/handlers/.gitkeep

@@ -0,0 +1 @@
+# Placeholder for command handlers

package/lib/repo/handlers/exec-handler.js

@@ -0,0 +1,155 @@
+const RepoManager = require('../repo-manager');
+const ConfigManager = require('../config-manager');
+const OutputFormatter = require('../output-formatter');
+
+/**
+ * ExecHandler - Handles batch command execution across repositories
+ * 
+ * Executes Git commands across all configured repositories with
+ * support for dry-run mode and detailed result reporting.
+ */
+class ExecHandler {
+  /**
+   * Create a new ExecHandler
+   * @param {string} projectRoot - The project root directory
+   */
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.repoManager = new RepoManager(projectRoot);
+    this.configManager = new ConfigManager(projectRoot);
+    this.formatter = new OutputFormatter();
+  }
+
+  /**
+   * Execute command across repositories
+   * @param {string} command - Git command to execute (without 'git' prefix)
+   * @param {Object} options - Execution options
+   * @param {boolean} options.dryRun - Show commands without executing
+   * @returns {Promise<void>}
+   */
+  async execute(command, options = {}) {
+    const { dryRun = false } = options;
+
+    if (!command || command.trim().length === 0) {
+      console.log(this.formatter.error('Command is required'));
+      throw new Error('Command is required');
+    }
+
+    // Load configuration
+    let config;
+    try {
+      config = await this.configManager.loadConfig();
+    } catch (error) {
+      console.log(this.formatter.error(error.message));
+      throw error;
+    }
+
+    if (config.repositories.length === 0) {
+      console.log(this.formatter.warning('No repositories configured'));
+      return;
+    }
+
+    // Dry-run mode: just display what would be executed
+    if (dryRun) {
+      console.log(this.formatter.info('Dry-run mode: Commands that would be executed:'));
+      console.log('');
+      config.repositories.forEach(repo => {
+        console.log(`${this.formatter.info('Repository:')} ${repo.name} (${repo.path})`);
+        console.log(`  Command: git ${command}`);
+        console.log('');
+      });
+      return;
+    }
+
+    // Execute command in all repositories
+    const progress = this.formatter.createProgress('Executing command...');
+    progress.start();
+
+    let results;
+    try {
+      results = await this.repoManager.execInAllRepos(config.repositories, command);
+      progress.stop();
+    } catch (error) {
+      progress.fail('Failed to execute command');
+      throw error;
+    }
+
+    // Display results
+    this.displayResults(results);
+
+    // Display summary
+    this.displaySummary(results);
+  }
+
+  /**
+   * Display execution results
+   * @param {Array<Object>} results - Array of execution results
+   */
+  displayResults(results) {
+    console.log('\n' + this.formatter.info('Execution Results'));
+    console.log('='.repeat(80));
+
+    results.forEach((result, index) => {
+      if (index > 0) {
+        console.log('\n' + '-'.repeat(80));
+      }
+
+      console.log(`\n${this.formatter.info('Repository:')} ${result.name} (${result.path})`);
+      console.log(`${this.formatter.info('Command:')} git ${result.command}`);
+
+      if (result.success) {
+        console.log(this.formatter.success('Status: Success'));
+        if (result.output && result.output.length > 0) {
+          console.log('\nOutput:');
+          console.log(result.output);
+        } else {
+          console.log(this.formatter.info('(No output)'));
+        }
+      } else {
+        console.log(this.formatter.error(`Status: Failed (exit code: ${result.exitCode})`));
+        if (result.error) {
+          console.log('\nError:');
+          console.log(this.formatter.error(result.error));
+        }
+      }
+    });
+
+    console.log('\n' + '='.repeat(80));
+  }
+
+  /**
+   * Display execution summary
+   * @param {Array<Object>} results - Array of execution results
+   */
+  displaySummary(results) {
+    const successCount = results.filter(r => r.success).length;
+    const failureCount = results.filter(r => !r.success).length;
+    const totalCount = results.length;
+
+    console.log('\n' + this.formatter.info('Summary'));
+    console.log(`  Total repositories: ${totalCount}`);
+    console.log(`  ${this.formatter.success(`Successful: ${successCount}`)}`);
+    
+    if (failureCount > 0) {
+      console.log(`  ${this.formatter.error(`Failed: ${failureCount}`)}`);
+      
+      // List failed repositories
+      const failedRepos = results.filter(r => !r.success);
+      console.log('\nFailed repositories:');
+      failedRepos.forEach(result => {
+        console.log(`  - ${result.name} (${result.path}): ${result.error}`);
+      });
+    }
+
+    // Display exit codes for failed commands
+    const failedWithExitCodes = results.filter(r => !r.success && r.exitCode !== 0);
+    if (failedWithExitCodes.length > 0) {
+      console.log('\nExit codes:');
+      failedWithExitCodes.forEach(result => {
+        console.log(`  - ${result.name}: ${result.exitCode}`);
+      });
+    }
+  }
+}
+
+module.exports = ExecHandler;

package/lib/repo/handlers/health-handler.js

@@ -0,0 +1,169 @@
+const RepoManager = require('../repo-manager');
+const ConfigManager = require('../config-manager');
+const OutputFormatter = require('../output-formatter');
+
+/**
+ * HealthHandler - Handles repository health check command
+ * 
+ * Performs comprehensive health checks on all configured repositories
+ * including path validation, Git repository verification, remote
+ * reachability, and branch existence.
+ */
+class HealthHandler {
+  /**
+   * Create a new HealthHandler
+   * @param {string} projectRoot - The project root directory
+   */
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.repoManager = new RepoManager(projectRoot);
+    this.configManager = new ConfigManager(projectRoot);
+    this.formatter = new OutputFormatter();
+  }
+
+  /**
+   * Execute health check
+   * @param {Object} options - Health check options
+   * @returns {Promise<void>}
+   */
+  async execute(options = {}) {
+    // Load configuration
+    let config;
+    try {
+      config = await this.configManager.loadConfig();
+    } catch (error) {
+      console.log(this.formatter.error(error.message));
+      throw error;
+    }
+
+    if (config.repositories.length === 0) {
+      console.log(this.formatter.warning('No repositories configured'));
+      return;
+    }
+
+    // Perform health checks
+    const progress = this.formatter.createProgress('Performing health checks...');
+    progress.start();
+
+    let results;
+    try {
+      results = await this.repoManager.checkAllReposHealth(config.repositories);
+      progress.stop();
+    } catch (error) {
+      progress.fail('Failed to perform health checks');
+      throw error;
+    }
+
+    // Display results
+    this.displayResults(results);
+
+    // Display summary
+    this.displaySummary(results);
+  }
+
+  /**
+   * Display health check results
+   * @param {Array<Object>} results - Array of health check results
+   */
+  displayResults(results) {
+    console.log('\n' + this.formatter.info('Health Check Results'));
+    console.log('='.repeat(80));
+
+    results.forEach((result, index) => {
+      if (index > 0) {
+        console.log('\n' + '-'.repeat(80));
+      }
+
+      console.log(`\n${this.formatter.info('Repository:')} ${result.name} (${result.path})`);
+
+      // Overall health status
+      if (result.healthy) {
+        console.log(this.formatter.success('Status: Healthy ✓'));
+      } else {
+        console.log(this.formatter.error('Status: Unhealthy ✗'));
+      }
+
+      // Display individual checks
+      console.log('\nChecks:');
+      console.log(`  Path exists: ${this._formatCheckResult(result.checks.pathExists)}`);
+      console.log(`  Is Git repository: ${this._formatCheckResult(result.checks.isGitRepo)}`);
+      
+      if (result.checks.remoteReachable !== null) {
+        console.log(`  Remote reachable: ${this._formatCheckResult(result.checks.remoteReachable)}`);
+      }
+      
+      if (result.checks.branchExists !== null) {
+        console.log(`  Branch exists: ${this._formatCheckResult(result.checks.branchExists)}`);
+      }
+
+      // Display errors
+      if (result.errors.length > 0) {
+        console.log('\n' + this.formatter.error('Errors:'));
+        result.errors.forEach(error => {
+          console.log(`  ${this.formatter.error('•')} ${error}`);
+        });
+      }
+
+      // Display warnings
+      if (result.warnings.length > 0) {
+        console.log('\n' + this.formatter.warning('Warnings:'));
+        result.warnings.forEach(warning => {
+          console.log(`  ${this.formatter.warning('•')} ${warning}`);
+        });
+      }
+    });
+
+    console.log('\n' + '='.repeat(80));
+  }
+
+  /**
+   * Display health summary
+   * @param {Array<Object>} results - Array of health check results
+   */
+  displaySummary(results) {
+    const healthyCount = results.filter(r => r.healthy).length;
+    const unhealthyCount = results.filter(r => !r.healthy).length;
+    const totalCount = results.length;
+
+    console.log('\n' + this.formatter.info('Overall Health Summary'));
+    console.log(`  Total repositories: ${totalCount}`);
+    console.log(`  ${this.formatter.success(`Healthy: ${healthyCount}`)}`);
+    
+    if (unhealthyCount > 0) {
+      console.log(`  ${this.formatter.error(`Unhealthy: ${unhealthyCount}`)}`);
+      
+      // List unhealthy repositories
+      const unhealthyRepos = results.filter(r => !r.healthy);
+      console.log('\nUnhealthy repositories:');
+      unhealthyRepos.forEach(result => {
+        const mainError = result.errors.length > 0 ? result.errors[0] : 'Unknown error';
+        console.log(`  - ${result.name} (${result.path}): ${mainError}`);
+      });
+    } else {
+      console.log('\n' + this.formatter.success('All repositories are healthy! 🎉'));
+    }
+
+    // Display warning summary
+    const reposWithWarnings = results.filter(r => r.warnings.length > 0);
+    if (reposWithWarnings.length > 0) {
+      console.log('\n' + this.formatter.warning(`${reposWithWarnings.length} ${reposWithWarnings.length === 1 ? 'repository has' : 'repositories have'} warnings:`));
+      reposWithWarnings.forEach(result => {
+        console.log(`  - ${result.name}: ${result.warnings.length} ${result.warnings.length === 1 ? 'warning' : 'warnings'}`);
+      });
+    }
+  }
+
+  /**
+   * Format check result as colored string
+   * @private
+   * @param {boolean} passed - Whether the check passed
+   * @returns {string} Formatted check result
+   */
+  _formatCheckResult(passed) {
+    return passed 
+      ? this.formatter.success('✓ Pass')
+      : this.formatter.error('✗ Fail');
+  }
+}
+
+module.exports = HealthHandler;

package/lib/repo/handlers/init-handler.js

@@ -0,0 +1,197 @@
+const readline = require('readline');
+const RepoManager = require('../repo-manager');
+const ConfigManager = require('../config-manager');
+const OutputFormatter = require('../output-formatter');
+
+/**
+ * InitHandler - Handles repository initialization command
+ * 
+ * Scans the project directory for Git repositories and creates
+ * the project-repos.json configuration file.
+ */
+class InitHandler {
+  /**
+   * Create a new InitHandler
+   * @param {string} projectRoot - The project root directory
+   */
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.repoManager = new RepoManager(projectRoot);
+    this.configManager = new ConfigManager(projectRoot);
+    this.formatter = new OutputFormatter();
+  }
+
+  /**
+   * Execute repository initialization
+   * @param {Object} options - Initialization options
+   * @param {boolean} options.yes - Skip confirmation prompts
+   * @param {number} options.maxDepth - Maximum scan depth
+   * @param {string[]} options.exclude - Directories to exclude
+   * @param {boolean} options.nested - Enable nested repository scanning (default: true)
+   * @returns {Promise<Object>} Initialization result
+   */
+  async execute(options = {}) {
+    const { yes = false, maxDepth = 3, exclude = ['.kiro'], nested = true } = options;
+
+    // Check if configuration already exists
+    const configExists = await this.configManager.configExists();
+    
+    if (configExists && !yes) {
+      const shouldOverwrite = await this.confirmOverwrite();
+      if (!shouldOverwrite) {
+        console.log(this.formatter.info('Initialization cancelled'));
+        return { cancelled: true, discovered: [], nestedMode: nested };
+      }
+    }
+
+    // Scan for repositories
+    const scanMode = nested ? 'nested' : 'non-nested';
+    const progress = this.formatter.createProgress(`Scanning for Git repositories (${scanMode} mode)...`);
+    progress.start();
+
+    let discovered;
+    try {
+      discovered = await this.repoManager.discoverRepositories(this.projectRoot, {
+        maxDepth,
+        exclude,
+        nested
+      });
+      progress.succeed(`Found ${discovered.length} Git ${discovered.length === 1 ? 'repository' : 'repositories'} (${scanMode} scanning)`);
+    } catch (error) {
+      progress.fail('Failed to scan for repositories');
+      throw error;
+    }
+
+    if (discovered.length === 0) {
+      console.log(this.formatter.warning('No Git repositories found in the project directory'));
+      return { cancelled: false, discovered: [], nestedMode: nested };
+    }
+
+    // Create configuration
+    const config = {
+      version: '1.0',
+      repositories: discovered.map(repo => ({
+        name: repo.name,
+        path: repo.path,
+        remote: repo.remote,
+        defaultBranch: repo.branch,
+        parent: repo.parent || null // Include parent field
+      })),
+      settings: {
+        nestedMode: nested // Store nested mode setting
+      }
+    };
+
+    // Save configuration
+    try {
+      await this.configManager.saveConfig(config);
+    } catch (error) {
+      console.log(this.formatter.error(`Failed to save configuration: ${error.message}`));
+      
+      // Display detailed validation errors if available
+      if (error.details && error.details.errors && Array.isArray(error.details.errors)) {
+        console.log(this.formatter.error('\nValidation errors:'));
+        error.details.errors.forEach((err, index) => {
+          console.log(this.formatter.error(`  ${index + 1}. ${err}`));
+        });
+      }
+      
+      throw error;
+    }
+
+    // Display summary
+    this.displaySummary({ discovered, configPath: this.configManager.getConfigPath(), nestedMode: nested });
+
+    return { cancelled: false, discovered, nestedMode: nested };
+  }
+
+  /**
+   * Prompt user for confirmation if config exists
+   * @returns {Promise<boolean>} True if user confirms overwrite
+   */
+  async confirmOverwrite() {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    return new Promise((resolve) => {
+      rl.question(
+        this.formatter.warning('Configuration file already exists. Overwrite? (y/N): '),
+        (answer) => {
+          rl.close();
+          const normalized = answer.trim().toLowerCase();
+          resolve(normalized === 'y' || normalized === 'yes');
+        }
+      );
+    });
+  }
+
+  /**
+   * Display initialization summary
+   * @param {Object} result - Initialization result
+   * @param {Array} result.discovered - Discovered repositories
+   * @param {string} result.configPath - Configuration file path
+   * @param {boolean} result.nestedMode - Whether nested scanning was enabled
+   */
+  displaySummary(result) {
+    const { discovered, configPath, nestedMode } = result;
+
+    console.log('\n' + this.formatter.success('Repository configuration initialized'));
+    console.log(this.formatter.info(`Configuration saved to: ${configPath}`));
+    console.log(this.formatter.info(`Scan mode: ${nestedMode ? 'nested' : 'non-nested'}`));
+    console.log('\nDiscovered repositories:');
+
+    // Display table of discovered repositories with parent column
+    const hasNestedRepos = discovered.some(r => r.parent);
+    const headers = hasNestedRepos 
+      ? ['Name', 'Path', 'Branch', 'Has Remote', 'Parent']
+      : ['Name', 'Path', 'Branch', 'Has Remote'];
+
+    const tableData = discovered.map(repo => {
+      const row = [
+        repo.name,
+        repo.path,
+        repo.branch,
+        repo.hasRemote ? '✓' : '✗'
+      ];
+      if (hasNestedRepos) {
+        row.push(repo.parent || '');
+      }
+      return row;
+    });
+
+    const table = this.formatter.formatTable([], {
+      head: headers,
+      rows: tableData
+    });
+
+    console.log(table);
+
+    // Display warnings for repos without remotes
+    const reposWithoutRemotes = discovered.filter(r => !r.hasRemote);
+    if (reposWithoutRemotes.length > 0) {
+      console.log('\n' + this.formatter.warning(
+        `${reposWithoutRemotes.length} ${reposWithoutRemotes.length === 1 ? 'repository' : 'repositories'} without remote URLs:`
+      ));
+      reposWithoutRemotes.forEach(repo => {
+        console.log(`  - ${repo.name} (${repo.path})`);
+      });
+    }
+
+    // Display nested repository info
+    if (hasNestedRepos) {
+      const nestedRepos = discovered.filter(r => r.parent);
+      console.log('\n' + this.formatter.info(
+        `Found ${nestedRepos.length} nested ${nestedRepos.length === 1 ? 'repository' : 'repositories'}`
+      ));
+    }
+
+    console.log('\nNext steps:');
+    console.log('  • Run "kse repo status" to view repository status');
+    console.log('  • Run "kse repo health" to check repository health');
+    console.log('  • Run "kse repo exec <command>" to execute commands across all repos');
+  }
+}
+
+module.exports = InitHandler;