agileflow 2.87.0 → 2.89.0

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')}`;

package/tools/cli/lib/ide-errors.js

@@ -0,0 +1,233 @@
+/**
+ * ide-errors.js - Typed Exception Classes for IDE Installers
+ *
+ * Provides specific error types for common IDE setup failures.
+ * These errors carry context about what failed and why,
+ * enabling better error handling and user feedback.
+ */
+
+/**
+ * Base error class for IDE-related errors.
+ * All IDE errors extend this class.
+ */
+class IdeError extends Error {
+  /**
+   * @param {string} message - Error description
+   * @param {string} ideName - Name of the IDE (e.g., 'Claude Code', 'Cursor')
+   * @param {Object} [context={}] - Additional context about the error
+   */
+  constructor(message, ideName, context = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.ideName = ideName;
+    this.context = context;
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  /**
+   * Get a user-friendly description of the error
+   * @returns {string}
+   */
+  getUserMessage() {
+    return `${this.ideName}: ${this.message}`;
+  }
+}
+
+/**
+ * Thrown when IDE configuration directory is not found.
+ * Example: .claude directory doesn't exist, .cursor not found
+ */
+class IdeConfigNotFoundError extends IdeError {
+  /**
+   * @param {string} ideName - Name of the IDE
+   * @param {string} configPath - Expected config directory path
+   * @param {Object} [context={}] - Additional context
+   */
+  constructor(ideName, configPath, context = {}) {
+    super(`Configuration directory not found: ${configPath}`, ideName, {
+      configPath,
+      ...context,
+    });
+    this.configPath = configPath;
+  }
+
+  /**
+   * Get suggested action to fix the error
+   * @returns {string}
+   */
+  getSuggestedAction() {
+    return `Create the ${this.configPath} directory or run the IDE at least once to initialize it.`;
+  }
+}
+
+/**
+ * Thrown when command installation fails.
+ * Example: Failed to copy command files, directory creation failed
+ */
+class CommandInstallationError extends IdeError {
+  /**
+   * @param {string} ideName - Name of the IDE
+   * @param {string} commandName - Name of the command being installed
+   * @param {string} reason - Why the installation failed
+   * @param {Object} [context={}] - Additional context
+   */
+  constructor(ideName, commandName, reason, context = {}) {
+    super(`Failed to install command '${commandName}': ${reason}`, ideName, {
+      commandName,
+      reason,
+      ...context,
+    });
+    this.commandName = commandName;
+    this.reason = reason;
+  }
+
+  /**
+   * Get suggested action to fix the error
+   * @returns {string}
+   */
+  getSuggestedAction() {
+    if (this.reason.includes('permission')) {
+      return `Check file permissions for the installation directory.`;
+    }
+    if (this.reason.includes('disk')) {
+      return `Free up disk space and try again.`;
+    }
+    return `Try running the installation again or check the source files.`;
+  }
+}
+
+/**
+ * Thrown when a file operation fails due to permission issues.
+ * Example: Cannot write to config directory, read access denied
+ */
+class FilePermissionError extends IdeError {
+  /**
+   * @param {string} ideName - Name of the IDE
+   * @param {string} filePath - Path to the file/directory
+   * @param {string} operation - Operation that failed ('read', 'write', 'delete')
+   * @param {Object} [context={}] - Additional context
+   */
+  constructor(ideName, filePath, operation, context = {}) {
+    super(`Permission denied: cannot ${operation} '${filePath}'`, ideName, {
+      filePath,
+      operation,
+      ...context,
+    });
+    this.filePath = filePath;
+    this.operation = operation;
+  }
+
+  /**
+   * Get suggested action to fix the error
+   * @returns {string}
+   */
+  getSuggestedAction() {
+    return `Check permissions on '${this.filePath}' or run with appropriate privileges.`;
+  }
+}
+
+/**
+ * Thrown when content injection fails.
+ * Example: Template placeholder not found, dynamic content generation failed
+ */
+class ContentInjectionError extends IdeError {
+  /**
+   * @param {string} ideName - Name of the IDE
+   * @param {string} templateFile - Path to the template file
+   * @param {string} reason - Why injection failed
+   * @param {Object} [context={}] - Additional context
+   */
+  constructor(ideName, templateFile, reason, context = {}) {
+    super(`Content injection failed for '${templateFile}': ${reason}`, ideName, {
+      templateFile,
+      reason,
+      ...context,
+    });
+    this.templateFile = templateFile;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Thrown when cleanup operation fails.
+ * Example: Cannot remove old installation, locked files
+ */
+class CleanupError extends IdeError {
+  /**
+   * @param {string} ideName - Name of the IDE
+   * @param {string} targetPath - Path being cleaned up
+   * @param {string} reason - Why cleanup failed
+   * @param {Object} [context={}] - Additional context
+   */
+  constructor(ideName, targetPath, reason, context = {}) {
+    super(`Cleanup failed for '${targetPath}': ${reason}`, ideName, {
+      targetPath,
+      reason,
+      ...context,
+    });
+    this.targetPath = targetPath;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Thrown when IDE detection fails or returns unexpected results.
+ * Example: Multiple conflicting IDE configs found
+ */
+class IdeDetectionError extends IdeError {
+  /**
+   * @param {string} ideName - Name of the IDE
+   * @param {string} reason - Why detection failed
+   * @param {Object} [context={}] - Additional context
+   */
+  constructor(ideName, reason, context = {}) {
+    super(`IDE detection failed: ${reason}`, ideName, {
+      reason,
+      ...context,
+    });
+    this.reason = reason;
+  }
+}
+
+/**
+ * Wrap a function call and convert EACCES/EPERM errors to FilePermissionError
+ * @param {string} ideName - Name of the IDE
+ * @param {string} filePath - Path being accessed
+ * @param {string} operation - Operation type ('read', 'write', 'delete')
+ * @param {Function} fn - Async function to wrap
+ * @returns {Promise<any>} Result of the function
+ * @throws {FilePermissionError} If permission error occurs
+ */
+async function withPermissionHandling(ideName, filePath, operation, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      throw new FilePermissionError(ideName, filePath, operation, {
+        originalError: error.message,
+      });
+    }
+    throw error;
+  }
+}
+
+/**
+ * Check if an error is an IDE-related error
+ * @param {Error} error - Error to check
+ * @returns {boolean}
+ */
+function isIdeError(error) {
+  return error instanceof IdeError;
+}
+
+module.exports = {
+  IdeError,
+  IdeConfigNotFoundError,
+  CommandInstallationError,
+  FilePermissionError,
+  ContentInjectionError,
+  CleanupError,
+  IdeDetectionError,
+  withPermissionHandling,
+  isIdeError,
+};