agileflow 3.4.2 → 4.0.0-alpha.1

package/tools/cli/installers/ide/_base-ide.js

@@ -1,518 +0,0 @@
-/**
- * AgileFlow CLI - Base IDE Installer
- *
- * Abstract base class for IDE-specific installers.
- */
-
-const path = require('node:path');
-const fs = require('fs-extra');
-const chalk = require('chalk');
-const {
-  IdeConfigNotFoundError,
-  CommandInstallationError,
-  FilePermissionError,
-  CleanupError,
-  ContentInjectionError,
-  withPermissionHandling,
-} = require('../../lib/ide-errors');
-const {
-  replaceReferences,
-  createDocsReplacements,
-  injectContent: injectDynamicContentHelper,
-} = require('../../lib/content-transformer');
-
-/**
- * Base class for IDE-specific setup
- * All IDE handlers should extend this class
- */
-class BaseIdeSetup {
-  constructor(name, displayName = null, preferred = false) {
-    this.name = name;
-    this.displayName = displayName || name;
-    this.preferred = preferred;
-    this.configDir = null; // Override in subclasses
-    this.agileflowFolder = '.agileflow';
-    this.docsFolder = 'docs';
-  }
-
-  /**
-   * Set the AgileFlow folder name
-   * @param {string} folderName - The AgileFlow folder name
-   */
-  setAgileflowFolder(folderName) {
-    this.agileflowFolder = folderName;
-  }
-
-  /**
-   * Set the docs folder name
-   * @param {string} folderName - The docs folder name
-   */
-  setDocsFolder(folderName) {
-    this.docsFolder = folderName;
-  }
-
-  /**
-   * Replace docs/ references in content with custom folder name
-   * Uses content-transformer module for consistent replacements
-   * @param {string} content - File content
-   * @returns {string} Updated content
-   */
-  replaceDocsReferences(content) {
-    if (this.docsFolder === 'docs') {
-      return content; // No replacement needed
-    }
-
-    // Use content-transformer for standard replacements
-    let result = replaceReferences(content, createDocsReplacements(this.docsFolder));
-
-    // Additional patterns not covered by standard replacements
-    result = replaceReferences(result, {
-      'docs/)': `${this.docsFolder}/)`,
-    });
-
-    // Replace standalone "docs" word (not followed by .)
-    // Use replacement function to avoid $ in docsFolder being interpreted as regex backreference
-    result = result.replace(/\bdocs\b(?!\.)/g, () => this.docsFolder);
-
-    return result;
-  }
-
-  /**
-   * Inject dynamic content into template (agent lists, command lists)
-   * Uses content-transformer module for consistent injection
-   * @param {string} content - Template file content
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @param {Object} [options] - Additional injection options
-   * @param {boolean} [options.minimal] - When true, skip full list injection (use discovery pointers)
-   * @returns {string} Content with placeholders replaced
-   */
-  injectDynamicContent(content, agileflowDir, options = {}) {
-    // agileflowDir is the user's .agileflow installation directory
-    // which has agents/, commands/, skills/ at the root level
-    return injectDynamicContentHelper(content, {
-      coreDir: agileflowDir,
-      agileflowFolder: this.agileflowFolder,
-      version: this.getVersion(),
-      minimal: options.minimal || false,
-    });
-  }
-
-  /**
-   * Get the current AgileFlow version
-   * @returns {string} Version string
-   */
-  getVersion() {
-    try {
-      const packageJson = require('../../../../package.json');
-      return packageJson.version || 'unknown';
-    } catch {
-      return 'unknown';
-    }
-  }
-
-  /**
-   * Detect minimal context mode from project metadata.
-   * Reads the contextVerbosity setting from /configure.
-   * @param {string} projectDir - Project directory
-   * @returns {boolean} True if minimal mode should be used
-   */
-  _detectMinimalMode(projectDir) {
-    try {
-      const metadataPath = path.join(
-        projectDir,
-        this.docsFolder,
-        '00-meta',
-        'agileflow-metadata.json'
-      );
-      if (!fs.existsSync(metadataPath)) return false;
-      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
-      const mode = metadata?.features?.contextVerbosity?.mode;
-      if (mode === 'minimal') return true;
-      return false;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Main setup method - must be implemented by subclasses
-   * @param {string} projectDir - Project directory
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @param {Object} options - Setup options
-   */
-  async setup(projectDir, agileflowDir, options = {}) {
-    throw new Error(`setup() must be implemented by ${this.name} handler`);
-  }
-
-  /**
-   * Standard setup flow shared by most IDE installers.
-   * Handles cleanup, command/agent installation, and logging.
-   *
-   * @param {string} projectDir - Project directory
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @param {Object} config - Configuration options
-   * @param {string} config.targetSubdir - Target subdirectory name under configDir (e.g., 'commands', 'workflows')
-   * @param {string} config.agileflowFolder - AgileFlow folder name (e.g., 'agileflow', 'AgileFlow')
-   * @param {string} [config.commandLabel='commands'] - Label for commands in output (e.g., 'workflows')
-   * @param {string} [config.agentLabel='agents'] - Label for agents in output
-   * @param {boolean} [config.minimal=false] - When true, skip full agent/command list injection. Auto-detected from metadata if not set.
-   * @returns {Promise<{success: boolean, commands: number, agents: number}>}
-   */
-  async setupStandard(projectDir, agileflowDir, config) {
-    const {
-      targetSubdir,
-      agileflowFolder,
-      commandLabel = 'commands',
-      agentLabel = 'agents',
-      minimal: explicitMinimal,
-    } = config;
-
-    // Auto-detect minimal mode from /configure context verbosity setting
-    const minimal = explicitMinimal ?? this._detectMinimalMode(projectDir);
-
-    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
-
-    // Clean up old installation first
-    await this.cleanup(projectDir);
-
-    // Create target directory (e.g., .cursor/commands/AgileFlow)
-    const ideDir = path.join(projectDir, this.configDir);
-    const targetDir = path.join(ideDir, targetSubdir);
-    const agileflowTargetDir = path.join(targetDir, agileflowFolder);
-
-    // Install commands using shared recursive method
-    const commandsSource = path.join(agileflowDir, 'commands');
-    const commandResult = await this.installCommandsRecursive(
-      commandsSource,
-      agileflowTargetDir,
-      agileflowDir,
-      true, // Inject dynamic content
-      null, // No IDE transform
-      { minimal } // Pass minimal flag for content injection
-    );
-
-    // Install agents as subdirectory
-    const agentsSource = path.join(agileflowDir, 'agents');
-    const agentsTargetDir = path.join(agileflowTargetDir, 'agents');
-    const agentResult = await this.installCommandsRecursive(
-      agentsSource,
-      agentsTargetDir,
-      agileflowDir,
-      false // No dynamic content for agents
-    );
-
-    console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
-    console.log(chalk.dim(`    - ${commandResult.commands} ${commandLabel} installed`));
-    console.log(chalk.dim(`    - ${agentResult.commands} ${agentLabel} installed`));
-    console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowTargetDir)}`));
-
-    return {
-      success: true,
-      commands: commandResult.commands,
-      agents: agentResult.commands,
-      ideDir,
-      agileflowTargetDir,
-    };
-  }
-
-  /**
-   * Cleanup IDE configuration
-   * @param {string} projectDir - Project directory
-   * @throws {CleanupError} If cleanup fails
-   */
-  async cleanup(projectDir) {
-    if (this.configDir) {
-      // Clean up both old (AgileFlow) and new (agileflow) folder names
-      for (const folderName of ['agileflow', 'AgileFlow']) {
-        const agileflowPath = path.join(projectDir, this.configDir, 'commands', folderName);
-        if (await fs.pathExists(agileflowPath)) {
-          try {
-            await fs.remove(agileflowPath);
-            console.log(
-              chalk.dim(`  Removed old ${folderName} configuration from ${this.displayName}`)
-            );
-          } catch (error) {
-            if (error.code === 'EACCES' || error.code === 'EPERM') {
-              throw new CleanupError(
-                this.displayName,
-                agileflowPath,
-                `Permission denied: ${error.message}`
-              );
-            }
-            throw new CleanupError(this.displayName, agileflowPath, error.message);
-          }
-        }
-      }
-
-      // Remove duplicate command files that exist outside the agileflow/ subfolder
-      // These cause "command 2" entries in Claude Code's autocomplete
-      await this.removeDuplicateCommands(projectDir);
-    }
-  }
-
-  /**
-   * Remove duplicate AgileFlow command files from the parent commands directory.
-   * When commands exist both in .claude/commands/agileflow/foo.md AND .claude/commands/foo.md,
-   * Claude Code shows them as "foo" and "foo 2" in autocomplete. This removes the loose copies.
-   * @param {string} projectDir - Project directory
-   */
-  async removeDuplicateCommands(projectDir) {
-    const commandsDir = path.join(projectDir, this.configDir, 'commands');
-    const agileflowDir = path.join(commandsDir, 'agileflow');
-
-    if (!(await fs.pathExists(commandsDir))) return;
-
-    // Get list of AgileFlow command names (files and directories)
-    const agileflowNames = new Set();
-    if (await fs.pathExists(agileflowDir)) {
-      const entries = await fs.readdir(agileflowDir, { withFileTypes: true });
-      for (const entry of entries) {
-        agileflowNames.add(entry.name);
-      }
-    }
-
-    // Also collect names from the source commands to catch pre-existing stale copies
-    const coreCommandsDir = path.join(projectDir, this.agileflowFolder, 'commands');
-    if (await fs.pathExists(coreCommandsDir)) {
-      const entries = await fs.readdir(coreCommandsDir, { withFileTypes: true });
-      for (const entry of entries) {
-        agileflowNames.add(entry.name);
-      }
-    }
-
-    if (agileflowNames.size === 0) return;
-
-    // Scan the parent commands directory for loose duplicates
-    let removedCount = 0;
-    const entries = await fs.readdir(commandsDir, { withFileTypes: true });
-
-    for (const entry of entries) {
-      // Skip the agileflow subfolder itself and non-agileflow items
-      if (entry.name === 'agileflow' || entry.name === 'AgileFlow') continue;
-
-      // Check if this file/directory matches an AgileFlow command name
-      if (agileflowNames.has(entry.name)) {
-        const duplicatePath = path.join(commandsDir, entry.name);
-        try {
-          await fs.remove(duplicatePath);
-          removedCount++;
-        } catch {
-          // Best effort - don't fail setup over cleanup
-        }
-      }
-    }
-
-    if (removedCount > 0) {
-      console.log(
-        chalk.dim(`  Removed ${removedCount} duplicate command(s) from ${this.displayName}`)
-      );
-    }
-  }
-
-  /**
-   * Detect if this IDE is configured in the project
-   * @param {string} projectDir - Project directory
-   * @returns {Promise<boolean>}
-   */
-  async detect(projectDir) {
-    if (this.configDir) {
-      const configPath = path.join(projectDir, this.configDir);
-      return fs.pathExists(configPath);
-    }
-    return false;
-  }
-
-  /**
-   * Ensure a directory exists
-   * @param {string} dirPath - Directory path
-   */
-  async ensureDir(dirPath) {
-    await fs.ensureDir(dirPath);
-  }
-
-  /**
-   * Write a file with permission error handling
-   * @param {string} filePath - File path
-   * @param {string} content - File content
-   * @throws {FilePermissionError} If permission denied
-   */
-  async writeFile(filePath, content) {
-    await withPermissionHandling(this.displayName, filePath, 'write', async () => {
-      await fs.writeFile(filePath, content, 'utf8');
-    });
-  }
-
-  /**
-   * Read a file with permission error handling
-   * @param {string} filePath - File path
-   * @returns {Promise<string>} File content
-   * @throws {FilePermissionError} If permission denied
-   */
-  async readFile(filePath) {
-    return withPermissionHandling(this.displayName, filePath, 'read', async () => {
-      return fs.readFile(filePath, 'utf8');
-    });
-  }
-
-  /**
-   * Check if a path exists
-   * @param {string} filePath - Path to check
-   * @returns {Promise<boolean>}
-   */
-  async exists(filePath) {
-    return fs.pathExists(filePath);
-  }
-
-  /**
-   * Scan a directory for files with a specific extension
-   * @param {string} dirPath - Directory path
-   * @param {string} extension - File extension (e.g., '.md')
-   * @param {string} [prefix=''] - Prefix for nested names (used for recursion)
-   * @returns {Promise<Array>} List of files with name, path, filename
-   */
-  async scanDirectory(dirPath, extension, prefix = '') {
-    const results = [];
-
-    if (!(await this.exists(dirPath))) {
-      return results;
-    }
-
-    const entries = await fs.readdir(dirPath, { withFileTypes: true });
-
-    for (const entry of entries) {
-      const fullPath = path.join(dirPath, entry.name);
-
-      if (entry.isFile() && entry.name.endsWith(extension)) {
-        // Build name with prefix for subcommands (e.g., ideate-new from ideate/new.md)
-        const baseName = entry.name.replace(extension, '');
-        const fullName = prefix ? `${prefix}-${baseName}` : baseName;
-
-        results.push({
-          name: fullName,
-          path: fullPath,
-          filename: entry.name,
-        });
-      } else if (entry.isDirectory()) {
-        // Recursively scan subdirectories with prefix
-        const subPrefix = prefix ? `${prefix}-${entry.name}` : entry.name;
-        const subResults = await this.scanDirectory(fullPath, extension, subPrefix);
-        results.push(...subResults);
-      }
-    }
-
-    return results;
-  }
-
-  /**
-   * Recursively install markdown files from source to target directory
-   * Handles content injection and docs reference replacement.
-   * Optionally applies IDE-specific transformations via ideTransform callback.
-   *
-   * @param {string} sourceDir - Source directory path
-   * @param {string} targetDir - Target directory path
-   * @param {string} agileflowDir - AgileFlow installation directory (for dynamic content)
-   * @param {boolean} injectDynamic - Whether to inject dynamic content (only for top-level commands)
-   * @param {Function} [ideTransform] - Optional IDE transformation function: (content, filename) => string
-   * @param {Object} [injectionOptions] - Options passed to injectDynamicContent (e.g., { minimal: true })
-   * @returns {Promise<{commands: number, subdirs: number}>} Count of installed items
-   * @throws {CommandInstallationError} If command installation fails
-   * @throws {FilePermissionError} If permission denied
-   *
-   * @example
-   * // Without transformation (backward compatible)
-   * await installer.installCommandsRecursive(src, target, agileflow, true);
-   *
-   * @example
-   * // With IDE transformation
-   * await installer.installCommandsRecursive(
-   *   src,
-   *   target,
-   *   agileflow,
-   *   true,
-   *   (content, filename) => ideGenerator.generateForIde(content, 'cursor')
-   * );
-   */
-  async installCommandsRecursive(
-    sourceDir,
-    targetDir,
-    agileflowDir,
-    injectDynamic = false,
-    ideTransform = null,
-    injectionOptions = {}
-  ) {
-    let commandCount = 0;
-    let subdirCount = 0;
-
-    if (!(await this.exists(sourceDir))) {
-      return { commands: 0, subdirs: 0 };
-    }
-
-    try {
-      await this.ensureDir(targetDir);
-    } catch (error) {
-      if (error.code === 'EACCES' || error.code === 'EPERM') {
-        throw new FilePermissionError(this.displayName, targetDir, 'write');
-      }
-      throw error;
-    }
-
-    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
-
-    for (const entry of entries) {
-      const sourcePath = path.join(sourceDir, entry.name);
-      const targetPath = path.join(targetDir, entry.name);
-
-      if (entry.isFile() && entry.name.endsWith('.md')) {
-        try {
-          // Read and process .md file
-          let content = await this.readFile(sourcePath);
-
-          // Inject dynamic content if enabled (for top-level commands)
-          if (injectDynamic) {
-            try {
-              content = this.injectDynamicContent(content, agileflowDir, injectionOptions);
-            } catch (injectionError) {
-              throw new ContentInjectionError(this.displayName, sourcePath, injectionError.message);
-            }
-          }
-
-          // Replace docs/ references with custom folder name
-          content = this.replaceDocsReferences(content);
-
-          // Apply IDE-specific transformation if provided
-          if (ideTransform && typeof ideTransform === 'function') {
-            content = ideTransform(content, entry.name);
-          }
-
-          await this.writeFile(targetPath, content);
-          commandCount++;
-        } catch (error) {
-          // Re-throw typed errors as-is
-          if (error.name && error.name.includes('Error') && error.ideName) {
-            throw error;
-          }
-          throw new CommandInstallationError(this.displayName, entry.name, error.message, {
-            sourcePath,
-            targetPath,
-          });
-        }
-      } else if (entry.isDirectory()) {
-        // Recursively process subdirectory
-        const subResult = await this.installCommandsRecursive(
-          sourcePath,
-          targetPath,
-          agileflowDir,
-          false, // Don't inject dynamic content in subdirectories
-          ideTransform, // Pass ideTransform to recursive calls
-          injectionOptions // Pass injection options to recursive calls
-        );
-        commandCount += subResult.commands;
-        subdirCount += 1 + subResult.subdirs;
-      }
-    }
-
-    return { commands: commandCount, subdirs: subdirCount };
-  }
-}
-
-module.exports = { BaseIdeSetup };