BMAD-METHOD/tools/cli/installers/lib/core/installer.js

const path = require('node:path');
const fs = require('fs-extra');
const chalk = require('chalk');
const ora = require('ora');
const { Detector } = require('./detector');
const { Manifest } = require('./manifest');
const { ModuleManager } = require('../modules/manager');
const { IdeManager } = require('../ide/manager');
const { FileOps } = require('../../../lib/file-ops');
const { Config } = require('../../../lib/config');
const { XmlHandler } = require('../../../lib/xml-handler');
const { DependencyResolver } = require('./dependency-resolver');
const { ConfigCollector } = require('./config-collector');
// processInstallation no longer needed - LLMs understand {project-root}
const { getProjectRoot, getSourcePath, getModulePath } = require('../../../lib/project-root');
const { AgentPartyGenerator } = require('../../../lib/agent-party-generator');
const { CLIUtils } = require('../../../lib/cli-utils');
const { ManifestGenerator } = require('./manifest-generator');

class Installer {
  constructor() {
    this.detector = new Detector();
    this.manifest = new Manifest();
    this.moduleManager = new ModuleManager();
    this.ideManager = new IdeManager();
    this.fileOps = new FileOps();
    this.config = new Config();
    this.xmlHandler = new XmlHandler();
    this.dependencyResolver = new DependencyResolver();
    this.configCollector = new ConfigCollector();
    this.installedFiles = []; // Track all installed files
  }

  /**
   * Collect Tool/IDE configurations after module configuration
   * @param {string} projectDir - Project directory
   * @param {Array} selectedModules - Selected modules from configuration
   * @returns {Object} Tool/IDE selection and configurations
   */
  async collectToolConfigurations(projectDir, selectedModules) {
    // Prompt for tool selection
    const { UI } = require('../../../lib/ui');
    const ui = new UI();
    const toolConfig = await ui.promptToolSelection(projectDir, selectedModules);

    // Collect IDE-specific configurations if any were selected
    const ideConfigurations = {};
    const bmadDir = path.join(projectDir, 'bmad');

    if (!toolConfig.skipIde && toolConfig.ides && toolConfig.ides.length > 0) {
      console.log('\n'); // Add spacing before IDE questions

      for (const ide of toolConfig.ides) {
        // List of IDEs that have interactive prompts
        const needsPrompts = ['claude-code', 'github-copilot', 'roo', 'cline', 'auggie', 'codex', 'qwen', 'gemini'].includes(ide);

        if (needsPrompts) {
          // Get IDE handler and collect configuration
          try {
            // Dynamically load the IDE setup module
            const ideModule = require(`../ide/${ide}`);

            // Get the setup class (handle different export formats)
            let SetupClass;
            const className =
              ide
                .split('-')
                .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
                .join('') + 'Setup';

            if (ideModule[className]) {
              SetupClass = ideModule[className];
            } else if (ideModule.default) {
              SetupClass = ideModule.default;
            } else {
              // Skip if no setup class found
              continue;
            }

            const ideSetup = new SetupClass();

            // Check if this IDE has a collectConfiguration method
            if (typeof ideSetup.collectConfiguration === 'function') {
              console.log(chalk.cyan(`\nConfiguring ${ide}...`));
              ideConfigurations[ide] = await ideSetup.collectConfiguration({
                selectedModules: selectedModules || [],
                projectDir,
                bmadDir,
              });
            }
          } catch {
            // IDE doesn't have a setup file or collectConfiguration method
            console.warn(chalk.yellow(`Warning: Could not load configuration for ${ide}`));
          }
        }
      }
    }

    return {
      ides: toolConfig.ides,
      skipIde: toolConfig.skipIde,
      configurations: ideConfigurations,
    };
  }

  /**
   * Main installation method
   * @param {Object} config - Installation configuration
   * @param {string} config.directory - Target directory
   * @param {boolean} config.installCore - Whether to install core
   * @param {string[]} config.modules - Modules to install
   * @param {string[]} config.ides - IDEs to configure
   * @param {boolean} config.skipIde - Skip IDE configuration
   */
  async install(config) {
    // Display BMAD logo
    CLIUtils.displayLogo();

    // Display welcome message
    CLIUtils.displaySection('BMAD™ Installation', 'Version ' + require(path.join(getProjectRoot(), 'package.json')).version);

    // Preflight: Handle legacy BMAD v4 footprints before any prompts/writes
    const projectDir = path.resolve(config.directory);
    const legacyV4 = await this.detector.detectLegacyV4(projectDir);
    if (legacyV4.hasLegacyV4) {
      await this.handleLegacyV4Migration(projectDir, legacyV4);
    }

    // If core config was pre-collected (from interactive mode), use it
    if (config.coreConfig) {
      this.configCollector.collectedConfig.core = config.coreConfig;
      // Also store in allAnswers for cross-referencing
      this.configCollector.allAnswers = {};
      for (const [key, value] of Object.entries(config.coreConfig)) {
        this.configCollector.allAnswers[`core_${key}`] = value;
      }
    }

    // Collect configurations for modules (core was already collected in UI.promptInstall if interactive)
    const moduleConfigs = await this.configCollector.collectAllConfigurations(config.modules || [], path.resolve(config.directory));

    const toolSelection = await this.collectToolConfigurations(path.resolve(config.directory), config.modules);

    // Merge tool selection into config
    config.ides = toolSelection.ides;
    config.skipIde = toolSelection.skipIde;
    const ideConfigurations = toolSelection.configurations;

    const spinner = ora('Preparing installation...').start();

    try {
      // Resolve target directory (path.resolve handles platform differences)
      const projectDir = path.resolve(config.directory);

      // Create a project directory if it doesn't exist (user already confirmed)
      if (!(await fs.pathExists(projectDir))) {
        spinner.text = 'Creating installation directory...';
        try {
          // fs.ensureDir handles platform-specific directory creation
          // It will recursively create all necessary parent directories
          await fs.ensureDir(projectDir);
        } catch (error) {
          spinner.fail('Failed to create installation directory');
          console.error(chalk.red(`Error: ${error.message}`));
          // More detailed error for common issues
          if (error.code === 'EACCES') {
            console.error(chalk.red('Permission denied. Check parent directory permissions.'));
          } else if (error.code === 'ENOSPC') {
            console.error(chalk.red('No space left on device.'));
          }
          throw new Error(`Cannot create directory: ${projectDir}`);
        }
      }

      const bmadDir = path.join(projectDir, 'bmad');

      // Check existing installation
      spinner.text = 'Checking for existing installation...';
      const existingInstall = await this.detector.detect(bmadDir);

      if (existingInstall.installed && !config.force) {
        spinner.stop();

        console.log(chalk.yellow('\n⚠️  Existing BMAD installation detected'));
        console.log(chalk.dim(`  Location: ${bmadDir}`));
        console.log(chalk.dim(`  Version: ${existingInstall.version}`));

        const { action } = await this.promptUpdateAction();
        if (action === 'cancel') {
          console.log('Installation cancelled.');
          return;
        }

        if (action === 'reinstall') {
          // Warn about destructive operation
          console.log(chalk.red.bold('\n⚠️  WARNING: This is a destructive operation!'));
          console.log(chalk.red('All custom files and modifications in the bmad directory will be lost.'));

          const inquirer = require('inquirer');
          const { confirmReinstall } = await inquirer.prompt([
            {
              type: 'confirm',
              name: 'confirmReinstall',
              message: chalk.yellow('Are you sure you want to delete and reinstall?'),
              default: false,
            },
          ]);

          if (!confirmReinstall) {
            console.log('Installation cancelled.');
            return;
          }

          // Remove existing installation
          await fs.remove(bmadDir);
          console.log(chalk.green('✓ Removed existing installation\n'));
        } else if (action === 'update') {
          // Store that we're updating for later processing
          config._isUpdate = true;
          config._existingInstall = existingInstall;

          // Detect custom and modified files BEFORE updating (compare current files vs files-manifest.csv)
          const existingFilesManifest = await this.readFilesManifest(bmadDir);
          console.log(chalk.dim(`DEBUG: Read ${existingFilesManifest.length} files from manifest`));
          console.log(chalk.dim(`DEBUG: Manifest has hashes: ${existingFilesManifest.some((f) => f.hash)}`));

          const { customFiles, modifiedFiles } = await this.detectCustomFiles(bmadDir, existingFilesManifest);

          console.log(chalk.dim(`DEBUG: Found ${customFiles.length} custom files, ${modifiedFiles.length} modified files`));
          if (modifiedFiles.length > 0) {
            console.log(chalk.yellow('DEBUG: Modified files:'));
            for (const f of modifiedFiles) console.log(chalk.dim(`  - ${f.path}`));
          }

          config._customFiles = customFiles;
          config._modifiedFiles = modifiedFiles;

          // If there are custom files, back them up temporarily
          if (customFiles.length > 0) {
            const tempBackupDir = path.join(projectDir, '.bmad-custom-backup-temp');
            await fs.ensureDir(tempBackupDir);

            spinner.start(`Backing up ${customFiles.length} custom files...`);
            for (const customFile of customFiles) {
              const relativePath = path.relative(bmadDir, customFile);
              const backupPath = path.join(tempBackupDir, relativePath);
              await fs.ensureDir(path.dirname(backupPath));
              await fs.copy(customFile, backupPath);
            }
            spinner.succeed(`Backed up ${customFiles.length} custom files`);

            config._tempBackupDir = tempBackupDir;
          }

          // For modified files, back them up to temp directory (will be restored as .bak files after install)
          if (modifiedFiles.length > 0) {
            const tempModifiedBackupDir = path.join(projectDir, '.bmad-modified-backup-temp');
            await fs.ensureDir(tempModifiedBackupDir);

            console.log(chalk.yellow(`\nDEBUG: Backing up ${modifiedFiles.length} modified files to temp location`));
            spinner.start(`Backing up ${modifiedFiles.length} modified files...`);
            for (const modifiedFile of modifiedFiles) {
              const relativePath = path.relative(bmadDir, modifiedFile.path);
              const tempBackupPath = path.join(tempModifiedBackupDir, relativePath);
              console.log(chalk.dim(`DEBUG: Backing up ${relativePath} to temp`));
              await fs.ensureDir(path.dirname(tempBackupPath));
              await fs.copy(modifiedFile.path, tempBackupPath, { overwrite: true });
            }
            spinner.succeed(`Backed up ${modifiedFiles.length} modified files`);

            config._tempModifiedBackupDir = tempModifiedBackupDir;
          } else {
            console.log(chalk.dim('DEBUG: No modified files detected'));
          }
        }
      }

      // Create bmad directory structure
      spinner.text = 'Creating directory structure...';
      await this.createDirectoryStructure(bmadDir);

      // Resolve dependencies for selected modules
      spinner.text = 'Resolving dependencies...';
      const projectRoot = getProjectRoot();
      const modulesToInstall = config.installCore ? ['core', ...config.modules] : config.modules;

      // For dependency resolution, we need to pass the project root
      const resolution = await this.dependencyResolver.resolve(projectRoot, config.modules || [], { verbose: config.verbose });

      if (config.verbose) {
        spinner.succeed('Dependencies resolved');
      } else {
        spinner.succeed('Dependencies resolved');
      }

      // Install core if requested or if dependencies require it
      if (config.installCore || resolution.byModule.core) {
        spinner.start('Installing BMAD core...');
        await this.installCoreWithDependencies(bmadDir, resolution.byModule.core);
        spinner.succeed('Core installed');
      }

      // Install modules with their dependencies
      if (config.modules && config.modules.length > 0) {
        for (const moduleName of config.modules) {
          spinner.start(`Installing module: ${moduleName}...`);
          await this.installModuleWithDependencies(moduleName, bmadDir, resolution.byModule[moduleName]);
          spinner.succeed(`Module installed: ${moduleName}`);
        }

        // Install partial modules (only dependencies)
        for (const [module, files] of Object.entries(resolution.byModule)) {
          if (!config.modules.includes(module) && module !== 'core') {
            const totalFiles = files.agents.length + files.tasks.length + files.templates.length + files.data.length + files.other.length;
            if (totalFiles > 0) {
              spinner.start(`Installing ${module} dependencies...`);
              await this.installPartialModule(module, bmadDir, files);
              spinner.succeed(`${module} dependencies installed`);
            }
          }
        }
      }

      // Generate clean config.yaml files for each installed module
      spinner.start('Generating module configurations...');
      await this.generateModuleConfigs(bmadDir, moduleConfigs);
      spinner.succeed('Module configurations generated');

      // Create agent configuration files
      spinner.start('Creating agent configurations...');
      // Get user info from collected config if available
      const userInfo = {
        userName: moduleConfigs.core?.['user_name'] || null,
        responseLanguage: moduleConfigs.core?.['communication_language'] || null,
      };
      const agentConfigResult = await this.createAgentConfigs(bmadDir, userInfo);
      if (agentConfigResult.skipped > 0) {
        spinner.succeed(`Agent configurations: ${agentConfigResult.created} created, ${agentConfigResult.skipped} preserved`);
      } else {
        spinner.succeed(`Agent configurations created: ${agentConfigResult.created}`);
      }

      // Pre-register manifest files that will be created (except files-manifest.csv to avoid recursion)
      const cfgDir = path.join(bmadDir, '_cfg');
      this.installedFiles.push(
        path.join(cfgDir, 'manifest.csv'),
        path.join(cfgDir, 'manifest.yaml'),
        path.join(cfgDir, 'workflow-manifest.csv'),
        path.join(cfgDir, 'agent-manifest.csv'),
        path.join(cfgDir, 'task-manifest.csv'),
      );

      // Generate CSV manifests for workflows, agents, tasks AND ALL FILES with hashes BEFORE IDE setup
      spinner.start('Generating workflow and agent manifests...');
      const manifestGen = new ManifestGenerator();
      const manifestStats = await manifestGen.generateManifests(bmadDir, config.modules || [], this.installedFiles);

      spinner.succeed(
        `Manifests generated: ${manifestStats.workflows} workflows, ${manifestStats.agents} agents, ${manifestStats.tasks} tasks, ${manifestStats.files} files`,
      );

      // Configure IDEs and copy documentation
      if (!config.skipIde && config.ides && config.ides.length > 0) {
        spinner.start('Configuring IDEs...');

        // Temporarily suppress console output if not verbose
        const originalLog = console.log;
        if (!config.verbose) {
          console.log = () => {};
        }

        for (const ide of config.ides) {
          spinner.text = `Configuring ${ide}...`;

          // Pass pre-collected configuration to avoid re-prompting
          await this.ideManager.setup(ide, projectDir, bmadDir, {
            selectedModules: config.modules || [],
            preCollectedConfig: ideConfigurations[ide] || null,
            verbose: config.verbose,
          });
        }

        // Restore console.log
        console.log = originalLog;

        spinner.succeed(`Configured ${config.ides.length} IDE${config.ides.length > 1 ? 's' : ''}`);

        // Copy IDE-specific documentation
        spinner.start('Copying IDE documentation...');
        await this.copyIdeDocumentation(config.ides, bmadDir);
        spinner.succeed('IDE documentation copied');
      }

      // Run module-specific installers after IDE setup
      spinner.start('Running module-specific installers...');

      // Run core module installer if core was installed
      if (config.installCore || resolution.byModule.core) {
        spinner.text = 'Running core module installer...';

        await this.moduleManager.runModuleInstaller('core', bmadDir, {
          installedIDEs: config.ides || [],
          moduleConfig: moduleConfigs.core || {},
          logger: {
            log: (msg) => console.log(msg),
            error: (msg) => console.error(msg),
            warn: (msg) => console.warn(msg),
          },
        });
      }

      // Run installers for user-selected modules
      if (config.modules && config.modules.length > 0) {
        for (const moduleName of config.modules) {
          spinner.text = `Running ${moduleName} module installer...`;

          // Pass installed IDEs and module config to module installer
          await this.moduleManager.runModuleInstaller(moduleName, bmadDir, {
            installedIDEs: config.ides || [],
            moduleConfig: moduleConfigs[moduleName] || {},
            logger: {
              log: (msg) => console.log(msg),
              error: (msg) => console.error(msg),
              warn: (msg) => console.warn(msg),
            },
          });
        }
      }

      spinner.succeed('Module-specific installers completed');

      // Create manifest
      spinner.start('Creating installation manifest...');
      const manifestResult = await this.manifest.create(
        bmadDir,
        {
          version: require(path.join(getProjectRoot(), 'package.json')).version,
          installDate: new Date().toISOString(),
          core: config.installCore,
          modules: config.modules || [],
          ides: config.ides || [],
          language: config.language || null,
        },
        this.installedFiles,
      );
      spinner.succeed(`Manifest created (${manifestResult.filesTracked} files tracked)`);

      // If this was an update, restore custom files
      let customFiles = [];
      let modifiedFiles = [];
      if (config._isUpdate) {
        if (config._customFiles && config._customFiles.length > 0) {
          spinner.start(`Restoring ${config._customFiles.length} custom files...`);

          for (const originalPath of config._customFiles) {
            const relativePath = path.relative(bmadDir, originalPath);
            const backupPath = path.join(config._tempBackupDir, relativePath);

            if (await fs.pathExists(backupPath)) {
              await fs.ensureDir(path.dirname(originalPath));
              await fs.copy(backupPath, originalPath, { overwrite: true });
            }
          }

          // Clean up temp backup
          if (config._tempBackupDir && (await fs.pathExists(config._tempBackupDir))) {
            await fs.remove(config._tempBackupDir);
          }

          spinner.succeed(`Restored ${config._customFiles.length} custom files`);
          customFiles = config._customFiles;
        }

        if (config._modifiedFiles && config._modifiedFiles.length > 0) {
          modifiedFiles = config._modifiedFiles;

          // Restore modified files as .bak files
          if (config._tempModifiedBackupDir && (await fs.pathExists(config._tempModifiedBackupDir))) {
            spinner.start(`Restoring ${modifiedFiles.length} modified files as .bak...`);

            for (const modifiedFile of modifiedFiles) {
              const relativePath = path.relative(bmadDir, modifiedFile.path);
              const tempBackupPath = path.join(config._tempModifiedBackupDir, relativePath);
              const bakPath = modifiedFile.path + '.bak';

              if (await fs.pathExists(tempBackupPath)) {
                await fs.ensureDir(path.dirname(bakPath));
                await fs.copy(tempBackupPath, bakPath, { overwrite: true });
              }
            }

            // Clean up temp backup
            await fs.remove(config._tempModifiedBackupDir);

            spinner.succeed(`Restored ${modifiedFiles.length} modified files as .bak`);
          }
        }
      }

      spinner.stop();

      // Report custom and modified files if any were found
      if (customFiles.length > 0) {
        console.log(chalk.cyan(`\n📁 Custom files preserved: ${customFiles.length}`));
        console.log(chalk.dim('The following custom files were found and restored:\n'));
        for (const file of customFiles) {
          console.log(chalk.dim(`  - ${path.relative(bmadDir, file)}`));
        }
        console.log('');
      }

      if (modifiedFiles.length > 0) {
        console.log(chalk.yellow(`\n⚠️  Modified files detected: ${modifiedFiles.length}`));
        console.log(chalk.dim('The following files were modified and backed up with .bak extension:\n'));
        for (const file of modifiedFiles) {
          console.log(chalk.dim(`  - ${file.relativePath} → ${file.relativePath}.bak`));
        }
        console.log(chalk.dim('\nThese files have been updated with the new version.'));
        console.log(chalk.dim('Review the .bak files to see your changes and merge if needed.\n'));
      }

      // Display completion message
      const { UI } = require('../../../lib/ui');
      const ui = new UI();
      ui.showInstallSummary({
        path: bmadDir,
        modules: config.modules,
        ides: config.ides,
        customFiles: customFiles.length > 0 ? customFiles : undefined,
      });

      return { success: true, path: bmadDir, modules: config.modules, ides: config.ides };
    } catch (error) {
      spinner.fail('Installation failed');
      throw error;
    }
  }

  /**
   * Update existing installation
   */
  async update(config) {
    const spinner = ora('Checking installation...').start();

    try {
      const bmadDir = path.join(path.resolve(config.directory), 'bmad');
      const existingInstall = await this.detector.detect(bmadDir);

      if (!existingInstall.installed) {
        spinner.fail('No BMAD installation found');
        throw new Error(`No BMAD installation found at ${bmadDir}`);
      }

      spinner.text = 'Analyzing update requirements...';

      // Compare versions and determine what needs updating
      const currentVersion = existingInstall.version;
      const newVersion = require(path.join(getProjectRoot(), 'package.json')).version;

      if (config.dryRun) {
        spinner.stop();
        console.log(chalk.cyan('\n🔍 Update Preview (Dry Run)\n'));
        console.log(chalk.bold('Current version:'), currentVersion);
        console.log(chalk.bold('New version:'), newVersion);
        console.log(chalk.bold('Core:'), existingInstall.hasCore ? 'Will be updated' : 'Not installed');

        if (existingInstall.modules.length > 0) {
          console.log(chalk.bold('\nModules to update:'));
          for (const mod of existingInstall.modules) {
            console.log(`  - ${mod.id}`);
          }
        }
        return;
      }

      // Perform actual update
      if (existingInstall.hasCore) {
        spinner.text = 'Updating core...';
        await this.updateCore(bmadDir, config.force);
      }

      for (const module of existingInstall.modules) {
        spinner.text = `Updating module: ${module.id}...`;
        await this.moduleManager.update(module.id, bmadDir, config.force);
      }

      // Update manifest
      spinner.text = 'Updating manifest...';
      await this.manifest.update(bmadDir, {
        version: newVersion,
        updateDate: new Date().toISOString(),
      });

      spinner.succeed('Update complete');
      return { success: true };
    } catch (error) {
      spinner.fail('Update failed');
      throw error;
    }
  }

  /**
   * Get installation status
   */
  async getStatus(directory) {
    const bmadDir = path.join(path.resolve(directory), 'bmad');
    return await this.detector.detect(bmadDir);
  }

  /**
   * Get available modules
   */
  async getAvailableModules() {
    return await this.moduleManager.listAvailable();
  }

  /**
   * Uninstall BMAD
   */
  async uninstall(directory) {
    const bmadDir = path.join(path.resolve(directory), 'bmad');

    if (await fs.pathExists(bmadDir)) {
      await fs.remove(bmadDir);
    }

    // Clean up IDE configurations
    await this.ideManager.cleanup(path.resolve(directory));

    return { success: true };
  }

  /**
   * Private: Create directory structure
   */
  async createDirectoryStructure(bmadDir) {
    await fs.ensureDir(bmadDir);
    await fs.ensureDir(path.join(bmadDir, '_cfg'));
    await fs.ensureDir(path.join(bmadDir, '_cfg', 'agents'));
  }

  /**
   * Generate clean config.yaml files for each installed module
   * @param {string} bmadDir - BMAD installation directory
   * @param {Object} moduleConfigs - Collected configuration values
   */
  async generateModuleConfigs(bmadDir, moduleConfigs) {
    const yaml = require('js-yaml');

    // Extract core config values to share with other modules
    const coreConfig = moduleConfigs.core || {};

    // Get all installed module directories
    const entries = await fs.readdir(bmadDir, { withFileTypes: true });
    const installedModules = entries
      .filter((entry) => entry.isDirectory() && entry.name !== '_cfg' && entry.name !== 'docs')
      .map((entry) => entry.name);

    // Generate config.yaml for each installed module
    for (const moduleName of installedModules) {
      const modulePath = path.join(bmadDir, moduleName);

      // Get module-specific config or use empty object if none
      const config = moduleConfigs[moduleName] || {};

      if (await fs.pathExists(modulePath)) {
        const configPath = path.join(modulePath, 'config.yaml');

        // Create header
        const packageJson = require(path.join(getProjectRoot(), 'package.json'));
        const header = `# ${moduleName.toUpperCase()} Module Configuration
# Generated by BMAD installer
# Version: ${packageJson.version}
# Date: ${new Date().toISOString()}

`;

        // For non-core modules, add core config values directly
        let finalConfig = { ...config };
        let coreSection = '';

        if (moduleName !== 'core' && coreConfig && Object.keys(coreConfig).length > 0) {
          // Add core values directly to the module config
          // These will be available for reference in the module
          finalConfig = {
            ...config,
            ...coreConfig, // Spread core config values directly into the module config
          };

          // Create a comment section to identify core values
          coreSection = '\n# Core Configuration Values\n';
        }

        // Convert config to YAML
        let yamlContent = yaml.dump(finalConfig, {
          indent: 2,
          lineWidth: -1,
          noRefs: true,
          sortKeys: false,
        });

        // If we have core values, reorganize the YAML to group them with their comment
        if (coreSection && moduleName !== 'core') {
          // Split the YAML into lines
          const lines = yamlContent.split('\n');
          const moduleConfigLines = [];
          const coreConfigLines = [];

          // Separate module-specific and core config lines
          for (const line of lines) {
            const key = line.split(':')[0].trim();
            if (Object.prototype.hasOwnProperty.call(coreConfig, key)) {
              coreConfigLines.push(line);
            } else {
              moduleConfigLines.push(line);
            }
          }

          // Rebuild YAML with module config first, then core config with comment
          yamlContent = moduleConfigLines.join('\n');
          if (coreConfigLines.length > 0) {
            yamlContent += coreSection + coreConfigLines.join('\n');
          }
        }

        // Write the clean config file
        await fs.writeFile(configPath, header + yamlContent, 'utf8');

        // Track the config file in installedFiles
        this.installedFiles.push(configPath);
      }
    }
  }

  /**
   * Install core with resolved dependencies
   * @param {string} bmadDir - BMAD installation directory
   * @param {Object} coreFiles - Core files to install
   */
  async installCoreWithDependencies(bmadDir, coreFiles) {
    const sourcePath = getModulePath('core');
    const targetPath = path.join(bmadDir, 'core');

    // Install full core
    await this.installCore(bmadDir);

    // If there are specific dependency files, ensure they're included
    if (coreFiles) {
      // Already handled by installCore for core module
    }
  }

  /**
   * Install module with resolved dependencies
   * @param {string} moduleName - Module name
   * @param {string} bmadDir - BMAD installation directory
   * @param {Object} moduleFiles - Module files to install
   */
  async installModuleWithDependencies(moduleName, bmadDir, moduleFiles) {
    // Use existing module manager for full installation with file tracking
    // Note: Module-specific installers are called separately after IDE setup
    await this.moduleManager.install(
      moduleName,
      bmadDir,
      (filePath) => {
        this.installedFiles.push(filePath);
      },
      {
        skipModuleInstaller: true, // We'll run it later after IDE setup
      },
    );

    // Dependencies are already included in full module install
  }

  /**
   * Install partial module (only dependencies needed by other modules)
   */
  async installPartialModule(moduleName, bmadDir, files) {
    const sourceBase = getModulePath(moduleName);
    const targetBase = path.join(bmadDir, moduleName);

    // Create module directory
    await fs.ensureDir(targetBase);

    // Copy only the required dependency files
    if (files.agents && files.agents.length > 0) {
      const agentsDir = path.join(targetBase, 'agents');
      await fs.ensureDir(agentsDir);

      for (const agentPath of files.agents) {
        const fileName = path.basename(agentPath);
        const sourcePath = path.join(sourceBase, 'agents', fileName);
        const targetPath = path.join(agentsDir, fileName);

        if (await fs.pathExists(sourcePath)) {
          await fs.copy(sourcePath, targetPath);
          this.installedFiles.push(targetPath);
        }
      }
    }

    if (files.tasks && files.tasks.length > 0) {
      const tasksDir = path.join(targetBase, 'tasks');
      await fs.ensureDir(tasksDir);

      for (const taskPath of files.tasks) {
        const fileName = path.basename(taskPath);
        const sourcePath = path.join(sourceBase, 'tasks', fileName);
        const targetPath = path.join(tasksDir, fileName);

        if (await fs.pathExists(sourcePath)) {
          await fs.copy(sourcePath, targetPath);
          this.installedFiles.push(targetPath);
        }
      }
    }

    if (files.templates && files.templates.length > 0) {
      const templatesDir = path.join(targetBase, 'templates');
      await fs.ensureDir(templatesDir);

      for (const templatePath of files.templates) {
        const fileName = path.basename(templatePath);
        const sourcePath = path.join(sourceBase, 'templates', fileName);
        const targetPath = path.join(templatesDir, fileName);

        if (await fs.pathExists(sourcePath)) {
          await fs.copy(sourcePath, targetPath);
          this.installedFiles.push(targetPath);
        }
      }
    }

    if (files.data && files.data.length > 0) {
      for (const dataPath of files.data) {
        // Preserve directory structure for data files
        const relative = path.relative(sourceBase, dataPath);
        const targetPath = path.join(targetBase, relative);

        await fs.ensureDir(path.dirname(targetPath));

        if (await fs.pathExists(dataPath)) {
          await fs.copy(dataPath, targetPath);
          this.installedFiles.push(targetPath);
        }
      }
    }

    // Create a marker file to indicate this is a partial installation
    const markerPath = path.join(targetBase, '.partial');
    await fs.writeFile(
      markerPath,
      `This module contains only dependencies required by other modules.\nInstalled: ${new Date().toISOString()}\n`,
    );
  }

  /**
   * Private: Install core
   * @param {string} bmadDir - BMAD installation directory
   */
  async installCore(bmadDir) {
    const sourcePath = getModulePath('core');
    const targetPath = path.join(bmadDir, 'core');

    // Copy core files with filtering for localskip agents
    await this.copyDirectoryWithFiltering(sourcePath, targetPath);

    // Process agent files to inject activation block
    await this.processAgentFiles(targetPath, 'core');
  }

  /**
   * Copy directory with filtering for localskip agents
   * @param {string} sourcePath - Source directory path
   * @param {string} targetPath - Target directory path
   */
  async copyDirectoryWithFiltering(sourcePath, targetPath) {
    // Get all files in source directory
    const files = await this.getFileList(sourcePath);

    for (const file of files) {
      // Skip config.yaml templates - we'll generate clean ones with actual values
      if (file === 'config.yaml' || file.endsWith('/config.yaml')) {
        continue;
      }

      const sourceFile = path.join(sourcePath, file);
      const targetFile = path.join(targetPath, file);

      // Check if this is an agent file
      if (file.includes('agents/') && file.endsWith('.md')) {
        // Read the file to check for localskip
        const content = await fs.readFile(sourceFile, 'utf8');

        // Check for localskip="true" in the agent tag
        const agentMatch = content.match(/<agent[^>]*\slocalskip="true"[^>]*>/);
        if (agentMatch) {
          console.log(chalk.dim(`  Skipping web-only agent: ${path.basename(file)}`));
          continue; // Skip this agent
        }
      }

      // Copy the file
      await fs.ensureDir(path.dirname(targetFile));
      await fs.copy(sourceFile, targetFile, { overwrite: true });

      // Track the installed file
      this.installedFiles.push(targetFile);
    }
  }

  /**
   * Get list of all files in a directory recursively
   * @param {string} dir - Directory path
   * @param {string} baseDir - Base directory for relative paths
   * @returns {Array} List of relative file paths
   */
  async getFileList(dir, baseDir = dir) {
    const files = [];
    const entries = await fs.readdir(dir, { withFileTypes: true });

    for (const entry of entries) {
      const fullPath = path.join(dir, entry.name);

      if (entry.isDirectory()) {
        // Skip _module-installer directories
        if (entry.name === '_module-installer') {
          continue;
        }
        const subFiles = await this.getFileList(fullPath, baseDir);
        files.push(...subFiles);
      } else {
        files.push(path.relative(baseDir, fullPath));
      }
    }

    return files;
  }

  /**
   * Process agent files to inject activation block
   * @param {string} modulePath - Path to module
   * @param {string} moduleName - Module name
   */
  async processAgentFiles(modulePath, moduleName) {
    const agentsPath = path.join(modulePath, 'agents');

    // Check if agents directory exists
    if (!(await fs.pathExists(agentsPath))) {
      return; // No agents to process
    }

    // Get all agent files
    const agentFiles = await fs.readdir(agentsPath);

    for (const agentFile of agentFiles) {
      if (!agentFile.endsWith('.md')) continue;

      const agentPath = path.join(agentsPath, agentFile);
      let content = await fs.readFile(agentPath, 'utf8');

      // Check if content has agent XML and no activation block
      if (content.includes('<agent') && !content.includes('<activation')) {
        // Inject the activation block using XML handler
        content = this.xmlHandler.injectActivationSimple(content);
        await fs.writeFile(agentPath, content, 'utf8');
      }
    }
  }

  /**
   * Private: Update core
   */
  async updateCore(bmadDir, force = false) {
    const sourcePath = getModulePath('core');
    const targetPath = path.join(bmadDir, 'core');

    if (force) {
      await fs.remove(targetPath);
      await this.installCore(bmadDir);
    } else {
      // Selective update - preserve user modifications
      await this.fileOps.syncDirectory(sourcePath, targetPath);
    }
  }

  /**
   * Private: Prompt for update action
   */
  async promptUpdateAction() {
    const inquirer = require('inquirer');
    return await inquirer.prompt([
      {
        type: 'list',
        name: 'action',
        message: 'What would you like to do?',
        choices: [
          { name: 'Update existing installation', value: 'update' },
          { name: 'Remove and reinstall', value: 'reinstall' },
          { name: 'Cancel', value: 'cancel' },
        ],
      },
    ]);
  }

  /**
   * Handle legacy BMAD v4 migration with automatic backup
   * @param {string} projectDir - Project directory
   * @param {Object} legacyV4 - Legacy V4 detection result with offenders array
   */
  async handleLegacyV4Migration(projectDir, legacyV4) {
    console.log(chalk.yellow.bold('\n⚠️  Legacy BMAD v4 detected'));
    console.log(chalk.dim('The installer found legacy artefacts in your project.\n'));

    // Separate .bmad* folders (auto-backup) from other offending paths (manual cleanup)
    const bmadFolders = legacyV4.offenders.filter((p) => {
      const name = path.basename(p);
      return name.startsWith('.bmad'); // Only dot-prefixed folders get auto-backed up
    });
    const otherOffenders = legacyV4.offenders.filter((p) => {
      const name = path.basename(p);
      return !name.startsWith('.bmad'); // Everything else is manual cleanup
    });

    const inquirer = require('inquirer');

    // Show warning for other offending paths FIRST
    if (otherOffenders.length > 0) {
      console.log(chalk.yellow('⚠️  Recommended cleanup:'));
      console.log(chalk.dim('It is recommended to remove the following items before proceeding:\n'));
      for (const p of otherOffenders) console.log(chalk.dim(` - ${p}`));

      console.log(chalk.cyan('\nCleanup commands you can copy/paste:'));
      console.log(chalk.dim('macOS/Linux:'));
      for (const p of otherOffenders) console.log(chalk.dim(`  rm -rf '${p}'`));
      console.log(chalk.dim('Windows:'));
      for (const p of otherOffenders) console.log(chalk.dim(`  rmdir /S /Q "${p}"`));

      const { cleanedUp } = await inquirer.prompt([
        {
          type: 'confirm',
          name: 'cleanedUp',
          message: 'Have you completed the recommended cleanup? (You can proceed without it, but it is recommended)',
          default: false,
        },
      ]);

      if (cleanedUp) {
        console.log(chalk.green('✓ Cleanup acknowledged\n'));
      } else {
        console.log(chalk.yellow('⚠️  Proceeding without recommended cleanup\n'));
      }
    }

    // Handle .bmad* folders with automatic backup
    if (bmadFolders.length > 0) {
      console.log(chalk.cyan('The following legacy folders will be moved to v4-backup:'));
      for (const p of bmadFolders) console.log(chalk.dim(` - ${p}`));

      const { proceed } = await inquirer.prompt([
        {
          type: 'confirm',
          name: 'proceed',
          message: 'Proceed with backing up legacy v4 folders?',
          default: true,
        },
      ]);

      if (proceed) {
        const backupDir = path.join(projectDir, 'v4-backup');
        await fs.ensureDir(backupDir);

        for (const folder of bmadFolders) {
          const folderName = path.basename(folder);
          const backupPath = path.join(backupDir, folderName);

          // If backup already exists, add timestamp
          let finalBackupPath = backupPath;
          if (await fs.pathExists(backupPath)) {
            const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-').split('T')[0];
            finalBackupPath = path.join(backupDir, `${folderName}-${timestamp}`);
          }

          await fs.move(folder, finalBackupPath, { overwrite: false });
          console.log(chalk.green(`✓ Moved ${folderName} to ${path.relative(projectDir, finalBackupPath)}`));
        }
      } else {
        throw new Error('Installation cancelled by user');
      }
    }
  }

  /**
   * Read files-manifest.csv
   * @param {string} bmadDir - BMAD installation directory
   * @returns {Array} Array of file entries from files-manifest.csv
   */
  async readFilesManifest(bmadDir) {
    const filesManifestPath = path.join(bmadDir, '_cfg', 'files-manifest.csv');
    if (!(await fs.pathExists(filesManifestPath))) {
      return [];
    }

    try {
      const content = await fs.readFile(filesManifestPath, 'utf8');
      const lines = content.split('\n');
      const files = [];

      for (let i = 1; i < lines.length; i++) {
        // Skip header
        const line = lines[i].trim();
        if (!line) continue;

        // Parse CSV line properly handling quoted values
        const parts = [];
        let current = '';
        let inQuotes = false;

        for (const char of line) {
          if (char === '"') {
            inQuotes = !inQuotes;
          } else if (char === ',' && !inQuotes) {
            parts.push(current);
            current = '';
          } else {
            current += char;
          }
        }
        parts.push(current); // Add last part

        if (parts.length >= 4) {
          files.push({
            type: parts[0],
            name: parts[1],
            module: parts[2],
            path: parts[3],
            hash: parts[4] || null, // Hash may not exist in old manifests
          });
        }
      }

      return files;
    } catch (error) {
      console.warn('Warning: Could not read files-manifest.csv:', error.message);
      return [];
    }
  }

  /**
   * Detect custom and modified files
   * @param {string} bmadDir - BMAD installation directory
   * @param {Array} existingFilesManifest - Previous files from files-manifest.csv
   * @returns {Object} Object with customFiles and modifiedFiles arrays
   */
  async detectCustomFiles(bmadDir, existingFilesManifest) {
    const customFiles = [];
    const modifiedFiles = [];

    // Check if the manifest has hashes - if not, we can't detect modifications
    let manifestHasHashes = false;
    if (existingFilesManifest && existingFilesManifest.length > 0) {
      manifestHasHashes = existingFilesManifest.some((f) => f.hash);
    }

    // Build map of previously installed files from files-manifest.csv with their hashes
    const installedFilesMap = new Map();
    for (const fileEntry of existingFilesManifest) {
      if (fileEntry.path) {
        // Files in manifest are stored as relative paths starting with 'bmad/'
        // Convert to absolute path
        const relativePath = fileEntry.path.startsWith('bmad/') ? fileEntry.path.slice(5) : fileEntry.path;
        const absolutePath = path.join(bmadDir, relativePath);
        installedFilesMap.set(path.normalize(absolutePath), {
          hash: fileEntry.hash,
          relativePath: relativePath,
        });
      }
    }

    // Recursively scan bmadDir for all files
    const scanDirectory = async (dir) => {
      try {
        const entries = await fs.readdir(dir, { withFileTypes: true });
        for (const entry of entries) {
          const fullPath = path.join(dir, entry.name);

          if (entry.isDirectory()) {
            // Skip certain directories
            if (entry.name === 'node_modules' || entry.name === '.git') {
              continue;
            }
            await scanDirectory(fullPath);
          } else if (entry.isFile()) {
            const normalizedPath = path.normalize(fullPath);
            const fileInfo = installedFilesMap.get(normalizedPath);

            // Skip certain system files that are auto-generated
            const relativePath = path.relative(bmadDir, fullPath);
            const fileName = path.basename(fullPath);

            // Skip _cfg directory - system files
            if (relativePath.startsWith('_cfg/') || relativePath.startsWith('_cfg\\')) {
              continue;
            }

            // Skip config.yaml files - these are regenerated on each install/update
            // Users should use _cfg/agents/ override files instead
            if (fileName === 'config.yaml') {
              continue;
            }

            if (!fileInfo) {
              // File not in manifest = custom file
              customFiles.push(fullPath);
            } else if (manifestHasHashes && fileInfo.hash) {
              // File in manifest with hash - check if it was modified
              const currentHash = await this.manifest.calculateFileHash(fullPath);
              if (currentHash && currentHash !== fileInfo.hash) {
                // Hash changed = file was modified
                modifiedFiles.push({
                  path: fullPath,
                  relativePath: fileInfo.relativePath,
                });
              }
            }
            // If manifest doesn't have hashes, we can't detect modifications
            // so we just skip files that are in the manifest
          }
        }
      } catch {
        // Ignore errors scanning directories
      }
    };

    await scanDirectory(bmadDir);
    return { customFiles, modifiedFiles };
  }

  /**
   * Private: Create agent configuration files
   * @param {string} bmadDir - BMAD installation directory
   * @param {Object} userInfo - User information including name and language
   */
  async createAgentConfigs(bmadDir, userInfo = null) {
    const agentConfigDir = path.join(bmadDir, '_cfg', 'agents');
    await fs.ensureDir(agentConfigDir);

    // Get all agents from all modules
    const agents = [];
    const agentDetails = []; // For manifest generation

    // Check modules for agents (including core)
    const entries = await fs.readdir(bmadDir, { withFileTypes: true });
    for (const entry of entries) {
      if (entry.isDirectory() && entry.name !== '_cfg') {
        const moduleAgentsPath = path.join(bmadDir, entry.name, 'agents');
        if (await fs.pathExists(moduleAgentsPath)) {
          const agentFiles = await fs.readdir(moduleAgentsPath);
          for (const agentFile of agentFiles) {
            if (agentFile.endsWith('.md')) {
              const agentPath = path.join(moduleAgentsPath, agentFile);
              const agentContent = await fs.readFile(agentPath, 'utf8');

              // Skip agents with localskip="true"
              const hasLocalSkip = agentContent.match(/<agent[^>]*\slocalskip="true"[^>]*>/);
              if (hasLocalSkip) {
                continue; // Skip this agent - it should not have been installed
              }

              const agentName = path.basename(agentFile, '.md');

              // Extract any nodes with agentConfig="true"
              const agentConfigNodes = this.extractAgentConfigNodes(agentContent);

              agents.push({
                name: agentName,
                module: entry.name,
                agentConfigNodes: agentConfigNodes,
              });

              // Use shared AgentPartyGenerator to extract details
              let details = AgentPartyGenerator.extractAgentDetails(agentContent, entry.name, agentName);

              // Apply config overrides if they exist
              if (details) {
                const configPath = path.join(agentConfigDir, `${entry.name}-${agentName}.md`);
                if (await fs.pathExists(configPath)) {
                  const configContent = await fs.readFile(configPath, 'utf8');
                  details = AgentPartyGenerator.applyConfigOverrides(details, configContent);
                }
                agentDetails.push(details);
              }
            }
          }
        }
      }
    }

    // Create config file for each agent
    let createdCount = 0;
    let skippedCount = 0;

    // Load agent config template
    const templatePath = getSourcePath('utility', 'models', 'agent-config-template.md');
    const templateContent = await fs.readFile(templatePath, 'utf8');

    for (const agent of agents) {
      const configPath = path.join(agentConfigDir, `${agent.module}-${agent.name}.md`);

      // Skip if config file already exists (preserve custom configurations)
      if (await fs.pathExists(configPath)) {
        skippedCount++;
        continue;
      }

      // Build config content header
      let configContent = `# Agent Config: ${agent.name}\n\n`;

      // Process template and add agent-specific config nodes
      let processedTemplate = templateContent;

      // Replace {core:user_name} placeholder with actual user name if available
      if (userInfo && userInfo.userName) {
        processedTemplate = processedTemplate.replaceAll('{core:user_name}', userInfo.userName);
      }

      // Replace {core:communication_language} placeholder with actual language if available
      if (userInfo && userInfo.responseLanguage) {
        processedTemplate = processedTemplate.replaceAll('{core:communication_language}', userInfo.responseLanguage);
      }

      // If this agent has agentConfig nodes, add them after the existing comment
      if (agent.agentConfigNodes && agent.agentConfigNodes.length > 0) {
        // Find the agent-specific configuration nodes comment
        const commentPattern = /(\s*<!-- Agent-specific configuration nodes -->)/;
        const commentMatch = processedTemplate.match(commentPattern);

        if (commentMatch) {
          // Add nodes right after the comment
          let agentSpecificNodes = '';
          for (const node of agent.agentConfigNodes) {
            agentSpecificNodes += `\n    ${node}`;
          }

          processedTemplate = processedTemplate.replace(commentPattern, `$1${agentSpecificNodes}`);
        }
      }

      configContent += processedTemplate;

      await fs.writeFile(configPath, configContent, 'utf8');
      this.installedFiles.push(configPath); // Track agent config files
      createdCount++;
    }

    // Generate agent manifest with overrides applied
    await this.generateAgentManifest(bmadDir, agentDetails);

    return { total: agents.length, created: createdCount, skipped: skippedCount };
  }

  /**
   * Generate agent manifest XML file
   * @param {string} bmadDir - BMAD installation directory
   * @param {Array} agentDetails - Array of agent details
   */
  async generateAgentManifest(bmadDir, agentDetails) {
    const manifestPath = path.join(bmadDir, '_cfg', 'agent-party.xml');
    await AgentPartyGenerator.writeAgentParty(manifestPath, agentDetails, { forWeb: false });
  }

  /**
   * Extract nodes with agentConfig="true" from agent content
   * @param {string} content - Agent file content
   * @returns {Array} Array of XML nodes that should be added to agent config
   */
  extractAgentConfigNodes(content) {
    const nodes = [];

    try {
      // Find all XML nodes with agentConfig="true"
      // Match self-closing tags and tags with content
      const selfClosingPattern = /<([a-zA-Z][a-zA-Z0-9_-]*)\s+[^>]*agentConfig="true"[^>]*\/>/g;
      const withContentPattern = /<([a-zA-Z][a-zA-Z0-9_-]*)\s+[^>]*agentConfig="true"[^>]*>([\s\S]*?)<\/\1>/g;

      // Extract self-closing tags
      let match;
      while ((match = selfClosingPattern.exec(content)) !== null) {
        // Extract just the tag without children (structure only)
        const tagMatch = match[0].match(/<([a-zA-Z][a-zA-Z0-9_-]*)([^>]*)\/>/);
        if (tagMatch) {
          const tagName = tagMatch[1];
          const attributes = tagMatch[2].replace(/\s*agentConfig="true"/, ''); // Remove agentConfig attribute
          nodes.push(`<${tagName}${attributes}></${tagName}>`);
        }
      }

      // Extract tags with content
      while ((match = withContentPattern.exec(content)) !== null) {
        const fullMatch = match[0];
        const tagName = match[1];

        // Extract opening tag with attributes (removing agentConfig="true")
        const openingTagMatch = fullMatch.match(new RegExp(`<${tagName}([^>]*)>`));
        if (openingTagMatch) {
          const attributes = openingTagMatch[1].replace(/\s*agentConfig="true"/, '');
          // Add empty node structure (no children)
          nodes.push(`<${tagName}${attributes}></${tagName}>`);
        }
      }
    } catch (error) {
      console.error('Error extracting agentConfig nodes:', error);
    }

    return nodes;
  }

  /**
   * Copy IDE-specific documentation to BMAD docs
   * @param {Array} ides - List of selected IDEs
   * @param {string} bmadDir - BMAD installation directory
   */
  async copyIdeDocumentation(ides, bmadDir) {
    const docsDir = path.join(bmadDir, 'docs');
    await fs.ensureDir(docsDir);

    for (const ide of ides) {
      const sourceDocPath = path.join(getProjectRoot(), 'docs', 'ide-info', `${ide}.md`);
      const targetDocPath = path.join(docsDir, `${ide}-instructions.md`);

      if (await fs.pathExists(sourceDocPath)) {
        await fs.copy(sourceDocPath, targetDocPath, { overwrite: true });
      }
    }
  }
}

module.exports = { Installer };