agileflow 2.88.0 → 2.89.0

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

@@ -7,6 +7,14 @@
 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');
 
 /**
  * Base class for IDE-specific setup
@@ -99,9 +107,74 @@ class BaseIdeSetup {
     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
+   * @returns {Promise<{success: boolean, commands: number, agents: number}>}
+   */
+  async setupStandard(projectDir, agileflowDir, config) {
+    const {
+      targetSubdir,
+      agileflowFolder,
+      commandLabel = 'commands',
+      agentLabel = 'agents',
+    } = config;
+
+    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
+    );
+
+    // 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) {
@@ -109,10 +182,25 @@ class BaseIdeSetup {
       for (const folderName of ['agileflow', 'AgileFlow']) {
         const agileflowPath = path.join(projectDir, this.configDir, 'commands', folderName);
         if (await fs.pathExists(agileflowPath)) {
-          await fs.remove(agileflowPath);
-          console.log(
-            chalk.dim(`  Removed old ${folderName} configuration from ${this.displayName}`)
-          );
+          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
+            );
+          }
         }
       }
     }
@@ -140,21 +228,27 @@ class BaseIdeSetup {
   }
 
   /**
-   * Write a file
+   * 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 fs.writeFile(filePath, content, 'utf8');
+    await withPermissionHandling(this.displayName, filePath, 'write', async () => {
+      await fs.writeFile(filePath, content, 'utf8');
+    });
   }
 
   /**
-   * Read a file
+   * 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 fs.readFile(filePath, 'utf8');
+    return withPermissionHandling(this.displayName, filePath, 'read', async () => {
+      return fs.readFile(filePath, 'utf8');
+    });
   }
 
   /**
@@ -202,6 +296,8 @@ class BaseIdeSetup {
    * @param {string} agileflowDir - AgileFlow installation directory (for dynamic content)
    * @param {boolean} injectDynamic - Whether to inject dynamic content (only for top-level commands)
    * @returns {Promise<{commands: number, subdirs: number}>} Count of installed items
+   * @throws {CommandInstallationError} If command installation fails
+   * @throws {FilePermissionError} If permission denied
    */
   async installCommandsRecursive(sourceDir, targetDir, agileflowDir, injectDynamic = false) {
     let commandCount = 0;
@@ -211,7 +307,14 @@ class BaseIdeSetup {
       return { commands: 0, subdirs: 0 };
     }
 
-    await this.ensureDir(targetDir);
+    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 });
 
@@ -220,19 +323,40 @@ class BaseIdeSetup {
       const targetPath = path.join(targetDir, entry.name);
 
       if (entry.isFile() && entry.name.endsWith('.md')) {
-        // Read and process .md file
-        let content = await this.readFile(sourcePath);
+        try {
+          // Read and process .md file
+          let content = await this.readFile(sourcePath);
 
-        // Inject dynamic content if enabled (for top-level commands)
-        if (injectDynamic) {
-          content = this.injectDynamicContent(content, agileflowDir);
-        }
+          // Inject dynamic content if enabled (for top-level commands)
+          if (injectDynamic) {
+            try {
+              content = this.injectDynamicContent(content, agileflowDir);
+            } catch (injectionError) {
+              throw new ContentInjectionError(
+                this.displayName,
+                sourcePath,
+                injectionError.message
+              );
+            }
+          }
 
-        // Replace docs/ references with custom folder name
-        content = this.replaceDocsReferences(content);
+          // Replace docs/ references with custom folder name
+          content = this.replaceDocsReferences(content);
 
-        await this.writeFile(targetPath, content);
-        commandCount++;
+          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(

package/tools/cli/installers/ide/claude-code.js

@@ -26,68 +26,31 @@ class ClaudeCodeSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, agileflowDir, options = {}) {
-    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
+    // Use standard setup for commands and agents
+    const result = await this.setupStandard(projectDir, agileflowDir, {
+      targetSubdir: this.commandsDir,
+      agileflowFolder: 'agileflow',
+    });
 
-    // Clean up old installation first
-    await this.cleanup(projectDir);
-
-    // Create .claude/commands/agileflow directory
-    const claudeDir = path.join(projectDir, this.configDir);
-    const commandsDir = path.join(claudeDir, this.commandsDir);
-    const agileflowCommandsDir = path.join(commandsDir, 'agileflow');
-
-    await this.ensureDir(agileflowCommandsDir);
-
-    // Recursively install all commands (including subdirectories like agents/, session/)
-    const commandsSource = path.join(agileflowDir, 'commands');
-    const commandResult = await this.installCommandsRecursive(
-      commandsSource,
-      agileflowCommandsDir,
-      agileflowDir,
-      true // Inject dynamic content for top-level commands
-    );
-
-    // Also install agents as slash commands (.claude/commands/agileflow/agents/)
+    const { ideDir, agileflowTargetDir } = result;
     const agentsSource = path.join(agileflowDir, 'agents');
-    const agentsTargetDir = path.join(agileflowCommandsDir, 'agents');
-    const agentResult = await this.installCommandsRecursive(
-      agentsSource,
-      agentsTargetDir,
-      agileflowDir,
-      false // No dynamic content for agents
-    );
-
-    // ALSO install agents as spawnable subagents (.claude/agents/agileflow/)
+
+    // Claude Code specific: Install agents as spawnable subagents (.claude/agents/agileflow/)
     // This allows Task tool to spawn them with subagent_type: "agileflow-ui"
-    const spawnableAgentsDir = path.join(claudeDir, 'agents', 'agileflow');
+    const spawnableAgentsDir = path.join(ideDir, 'agents', 'agileflow');
     await this.installCommandsRecursive(agentsSource, spawnableAgentsDir, agileflowDir, false);
     console.log(chalk.dim(`    - Spawnable agents: .claude/agents/agileflow/`));
 
-    // Create skills directory for user-generated skills (.claude/skills/)
+    // Claude Code specific: Create skills directory for user-generated skills
     // AgileFlow no longer ships static skills - users generate them via /agileflow:skill:create
-    const skillsTargetDir = path.join(claudeDir, 'skills');
+    const skillsTargetDir = path.join(ideDir, 'skills');
     await this.ensureDir(skillsTargetDir);
     console.log(chalk.dim(`    - Skills directory: .claude/skills/ (for user-generated skills)`));
 
-    // Setup damage control hooks
-    await this.setupDamageControl(projectDir, agileflowDir, claudeDir, options);
-
-    const totalCommands = commandResult.commands + agentResult.commands;
-    const totalSubdirs =
-      commandResult.subdirs + (agentResult.commands > 0 ? 1 : 0) + agentResult.subdirs;
-
-    console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
-    console.log(chalk.dim(`    - ${totalCommands} commands installed`));
-    if (totalSubdirs > 0) {
-      console.log(chalk.dim(`    - ${totalSubdirs} subdirectories`));
-    }
-    console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowCommandsDir)}`));
+    // Claude Code specific: Setup damage control hooks
+    await this.setupDamageControl(projectDir, agileflowDir, ideDir, options);
 
-    return {
-      success: true,
-      commands: totalCommands,
-      subdirs: totalSubdirs,
-    };
+    return result;
   }
 
   /**

package/tools/cli/installers/ide/cursor.js

@@ -7,7 +7,6 @@
 
 const path = require('node:path');
 const fs = require('fs-extra');
-const chalk = require('chalk');
 const { BaseIdeSetup } = require('./_base-ide');
 
 /**
@@ -27,45 +26,10 @@ class CursorSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, agileflowDir, options = {}) {
-    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
-
-    // Clean up old installation first
-    await this.cleanup(projectDir);
-
-    // Create .cursor/commands/AgileFlow directory
-    const cursorDir = path.join(projectDir, this.configDir);
-    const commandsDir = path.join(cursorDir, this.commandsDir);
-    const agileflowCommandsDir = path.join(commandsDir, 'AgileFlow');
-
-    // Install commands using shared recursive method
-    const commandsSource = path.join(agileflowDir, 'commands');
-    const commandResult = await this.installCommandsRecursive(
-      commandsSource,
-      agileflowCommandsDir,
-      agileflowDir,
-      true // Inject dynamic content
-    );
-
-    // Install agents as subdirectory
-    const agentsSource = path.join(agileflowDir, 'agents');
-    const agentsTargetDir = path.join(agileflowCommandsDir, '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} commands installed`));
-    console.log(chalk.dim(`    - ${agentResult.commands} agents installed`));
-    console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowCommandsDir)}`));
-
-    return {
-      success: true,
-      commands: commandResult.commands,
-      agents: agentResult.commands,
-    };
+    return this.setupStandard(projectDir, agileflowDir, {
+      targetSubdir: this.commandsDir,
+      agileflowFolder: 'AgileFlow',
+    });
   }
 
   /**

package/tools/cli/installers/ide/windsurf.js

@@ -7,7 +7,6 @@
 
 const path = require('node:path');
 const fs = require('fs-extra');
-const chalk = require('chalk');
 const { BaseIdeSetup } = require('./_base-ide');
 
 /**
@@ -27,45 +26,12 @@ class WindsurfSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, agileflowDir, options = {}) {
-    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
-
-    // Clean up old installation first
-    await this.cleanup(projectDir);
-
-    // Create .windsurf/workflows/agileflow directory
-    const windsurfDir = path.join(projectDir, this.configDir);
-    const workflowsDir = path.join(windsurfDir, this.workflowsDir);
-    const agileflowWorkflowsDir = path.join(workflowsDir, 'agileflow');
-
-    // Install commands using shared recursive method
-    const commandsSource = path.join(agileflowDir, 'commands');
-    const commandResult = await this.installCommandsRecursive(
-      commandsSource,
-      agileflowWorkflowsDir,
-      agileflowDir,
-      true // Inject dynamic content
-    );
-
-    // Install agents as subdirectory
-    const agentsSource = path.join(agileflowDir, 'agents');
-    const agentsTargetDir = path.join(agileflowWorkflowsDir, '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} workflows installed`));
-    console.log(chalk.dim(`    - ${agentResult.commands} agent workflows installed`));
-    console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowWorkflowsDir)}`));
-
-    return {
-      success: true,
-      commands: commandResult.commands,
-      agents: agentResult.commands,
-    };
+    return this.setupStandard(projectDir, agileflowDir, {
+      targetSubdir: this.workflowsDir,
+      agileflowFolder: 'agileflow',
+      commandLabel: 'workflows',
+      agentLabel: 'agent workflows',
+    });
   }
 
   /**

package/tools/cli/lib/content-injector.js

@@ -26,6 +26,7 @@ const path = require('path');
 
 // Use shared modules
 const { parseFrontmatter, normalizeTools } = require('../../../scripts/lib/frontmatter-parser');
+const { validatePath } = require('../../../lib/validate');
 const {
   countCommands,
   countAgents,
@@ -37,6 +38,18 @@ const {
 // List Generation Functions
 // =============================================================================
 
+/**
+ * Validate that a file path is within the expected directory.
+ * Prevents reading files outside the expected scope.
+ * @param {string} filePath - File path to validate
+ * @param {string} baseDir - Expected base directory
+ * @returns {boolean} True if path is safe
+ */
+function isPathSafe(filePath, baseDir) {
+  const result = validatePath(filePath, baseDir, { allowSymlinks: true });
+  return result.ok;
+}
+
 /**
  * Scan agents directory and generate formatted agent list
  * @param {string} agentsDir - Path to agents directory
@@ -50,6 +63,12 @@ function generateAgentList(agentsDir) {
 
   for (const file of files) {
     const filePath = path.join(agentsDir, file);
+
+    // Validate path before reading to prevent traversal via symlinks or malicious names
+    if (!isPathSafe(filePath, agentsDir)) {
+      continue;
+    }
+
     const content = fs.readFileSync(filePath, 'utf8');
     const frontmatter = parseFrontmatter(content);
 
@@ -94,6 +113,12 @@ function generateCommandList(commandsDir) {
   const mainFiles = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
   for (const file of mainFiles) {
     const filePath = path.join(commandsDir, file);
+
+    // Validate path before reading
+    if (!isPathSafe(filePath, commandsDir)) {
+      continue;
+    }
+
     const content = fs.readFileSync(filePath, 'utf8');
     const frontmatter = parseFrontmatter(content);
     const cmdName = path.basename(file, '.md');
@@ -114,10 +139,22 @@ function generateCommandList(commandsDir) {
   for (const entry of entries) {
     if (entry.isDirectory()) {
       const subDir = path.join(commandsDir, entry.name);
+
+      // Validate subdirectory path
+      if (!isPathSafe(subDir, commandsDir)) {
+        continue;
+      }
+
       const subFiles = fs.readdirSync(subDir).filter(f => f.endsWith('.md'));
 
       for (const file of subFiles) {
         const filePath = path.join(subDir, file);
+
+        // Validate file path within subdirectory
+        if (!isPathSafe(filePath, commandsDir)) {
+          continue;
+        }
+
         const content = fs.readFileSync(filePath, 'utf8');
         const frontmatter = parseFrontmatter(content);
         const cmdName = `${entry.name}:${path.basename(file, '.md')}`;