agileflow 2.87.0 → 2.89.0

package/scripts/damage-control-write.js

@@ -15,85 +15,20 @@
 const {
   findProjectRoot,
   loadPatterns,
-  pathMatches,
   outputBlocked,
   runDamageControlHook,
+  parsePathPatterns,
+  validatePathAgainstPatterns,
 } = require('./lib/damage-control-utils');
 
-/**
- * Parse simplified YAML for path patterns
- */
-function parseSimpleYAML(content) {
-  const config = {
-    zeroAccessPaths: [],
-    readOnlyPaths: [],
-    noDeletePaths: [],
-  };
-
-  let currentSection = null;
-
-  for (const line of content.split('\n')) {
-    const trimmed = line.trim();
-
-    // Skip empty lines and comments
-    if (!trimmed || trimmed.startsWith('#')) continue;
-
-    // Detect section headers
-    if (trimmed === 'zeroAccessPaths:') {
-      currentSection = 'zeroAccessPaths';
-    } else if (trimmed === 'readOnlyPaths:') {
-      currentSection = 'readOnlyPaths';
-    } else if (trimmed === 'noDeletePaths:') {
-      currentSection = 'noDeletePaths';
-    } else if (trimmed.endsWith(':') && !trimmed.startsWith('-')) {
-      // Other sections we don't care about for path validation
-      currentSection = null;
-    } else if (trimmed.startsWith('- ') && currentSection && config[currentSection]) {
-      // Path entry
-      const pathValue = trimmed.slice(2).replace(/^["']|["']$/g, '');
-      config[currentSection].push(pathValue);
-    }
-  }
-
-  return config;
-}
-
-/**
- * Validate file path for write operation
- */
-function validatePath(filePath, config) {
-  // Check zero access paths - completely blocked
-  const zeroMatch = pathMatches(filePath, config.zeroAccessPaths || []);
-  if (zeroMatch) {
-    return {
-      action: 'block',
-      reason: `Zero-access path: ${zeroMatch}`,
-      detail: 'This file is protected and cannot be accessed',
-    };
-  }
-
-  // Check read-only paths - cannot write
-  const readOnlyMatch = pathMatches(filePath, config.readOnlyPaths || []);
-  if (readOnlyMatch) {
-    return {
-      action: 'block',
-      reason: `Read-only path: ${readOnlyMatch}`,
-      detail: 'This file is read-only and cannot be written to',
-    };
-  }
-
-  // Allow by default
-  return { action: 'allow' };
-}
-
 // Run the hook
 const projectRoot = findProjectRoot();
 const defaultConfig = { zeroAccessPaths: [], readOnlyPaths: [], noDeletePaths: [] };
 
 runDamageControlHook({
   getInputValue: input => input.file_path || input.tool_input?.file_path,
-  loadConfig: () => loadPatterns(projectRoot, parseSimpleYAML, defaultConfig),
-  validate: validatePath,
+  loadConfig: () => loadPatterns(projectRoot, parsePathPatterns, defaultConfig),
+  validate: (filePath, config) => validatePathAgainstPatterns(filePath, config, 'write'),
   onBlock: (result, filePath) => {
     outputBlocked(result.reason, result.detail, `File: ${filePath}`);
   },

package/scripts/lib/damage-control-utils.js

@@ -238,6 +238,155 @@ function runDamageControlHook(options) {
   }, STDIN_TIMEOUT_MS);
 }
 
+/**
+ * Parse simplified YAML for damage control patterns
+ * Handles both pattern-based sections (with pattern/reason/flags objects)
+ * and list-based sections (with simple string arrays)
+ *
+ * @param {string} content - YAML file content
+ * @param {object} sectionConfig - Map of section names to their type ('patterns' or 'list')
+ * @returns {object} Parsed configuration
+ *
+ * @example
+ * // For bash patterns (pattern objects):
+ * parseSimpleYAML(content, {
+ *   bashToolPatterns: 'patterns',
+ *   askPatterns: 'patterns',
+ *   agileflowProtections: 'patterns',
+ * })
+ *
+ * @example
+ * // For path lists (string arrays):
+ * parseSimpleYAML(content, {
+ *   zeroAccessPaths: 'list',
+ *   readOnlyPaths: 'list',
+ *   noDeletePaths: 'list',
+ * })
+ */
+function parseSimpleYAML(content, sectionConfig) {
+  // Initialize result with empty arrays for each section
+  const config = {};
+  for (const section of Object.keys(sectionConfig)) {
+    config[section] = [];
+  }
+
+  let currentSection = null;
+  let currentPattern = null;
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+
+    // Skip empty lines and comments
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Check if this line is a section header we care about
+    const sectionMatch = trimmed.match(/^(\w+):$/);
+    if (sectionMatch) {
+      const sectionName = sectionMatch[1];
+      if (sectionConfig[sectionName]) {
+        currentSection = sectionName;
+        currentPattern = null;
+      } else {
+        // Section we don't care about
+        currentSection = null;
+        currentPattern = null;
+      }
+      continue;
+    }
+
+    // Skip if we're not in a tracked section
+    if (!currentSection) continue;
+
+    const sectionType = sectionConfig[currentSection];
+
+    if (sectionType === 'patterns') {
+      // Pattern-based section (objects with pattern/reason/flags)
+      if (trimmed.startsWith('- pattern:')) {
+        const patternValue = trimmed
+          .replace('- pattern:', '')
+          .trim()
+          .replace(/^["']|["']$/g, '');
+        currentPattern = { pattern: patternValue };
+        config[currentSection].push(currentPattern);
+      } else if (trimmed.startsWith('reason:') && currentPattern) {
+        currentPattern.reason = trimmed
+          .replace('reason:', '')
+          .trim()
+          .replace(/^["']|["']$/g, '');
+      } else if (trimmed.startsWith('flags:') && currentPattern) {
+        currentPattern.flags = trimmed
+          .replace('flags:', '')
+          .trim()
+          .replace(/^["']|["']$/g, '');
+      }
+    } else if (sectionType === 'list') {
+      // List-based section (simple string arrays)
+      if (trimmed.startsWith('- ')) {
+        const value = trimmed.slice(2).replace(/^["']|["']$/g, '');
+        config[currentSection].push(value);
+      }
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Pre-configured parser for bash tool patterns
+ */
+function parseBashPatterns(content) {
+  return parseSimpleYAML(content, {
+    bashToolPatterns: 'patterns',
+    askPatterns: 'patterns',
+    agileflowProtections: 'patterns',
+  });
+}
+
+/**
+ * Pre-configured parser for path patterns (edit/write)
+ */
+function parsePathPatterns(content) {
+  return parseSimpleYAML(content, {
+    zeroAccessPaths: 'list',
+    readOnlyPaths: 'list',
+    noDeletePaths: 'list',
+  });
+}
+
+/**
+ * Validate file path against path patterns
+ * Used by both edit and write hooks
+ *
+ * @param {string} filePath - File path to validate
+ * @param {object} config - Parsed path patterns config
+ * @param {string} operation - Operation type ('edit' or 'write') for error messages
+ * @returns {object} Validation result { action, reason?, detail? }
+ */
+function validatePathAgainstPatterns(filePath, config, operation = 'access') {
+  // Check zero access paths - completely blocked
+  const zeroMatch = pathMatches(filePath, config.zeroAccessPaths || []);
+  if (zeroMatch) {
+    return {
+      action: 'block',
+      reason: `Zero-access path: ${zeroMatch}`,
+      detail: 'This file is protected and cannot be accessed',
+    };
+  }
+
+  // Check read-only paths - cannot edit/write
+  const readOnlyMatch = pathMatches(filePath, config.readOnlyPaths || []);
+  if (readOnlyMatch) {
+    return {
+      action: 'block',
+      reason: `Read-only path: ${readOnlyMatch}`,
+      detail: `This file is read-only and cannot be ${operation === 'edit' ? 'edited' : 'written to'}`,
+    };
+  }
+
+  // Allow by default
+  return { action: 'allow' };
+}
+
 module.exports = {
   c,
   findProjectRoot,
@@ -246,6 +395,10 @@ module.exports = {
   pathMatches,
   outputBlocked,
   runDamageControlHook,
+  parseSimpleYAML,
+  parseBashPatterns,
+  parsePathPatterns,
+  validatePathAgainstPatterns,
   CONFIG_PATHS,
   STDIN_TIMEOUT_MS,
 };

package/scripts/obtain-context.js

@@ -20,6 +20,7 @@ const path = require('path');
 const { execSync } = require('child_process');
 const { c: C, box } = require('../lib/colors');
 const { isValidCommandName } = require('../lib/validate');
+const { readJSONCached, readFileCached } = require('../lib/file-cache');
 
 // Claude Code's Bash tool truncates around 30K chars, but ANSI codes and
 // box-drawing characters (╭╮╰╯─│) are multi-byte UTF-8, so we need buffer.
@@ -131,11 +132,9 @@ function safeRead(filePath) {
 }
 
 function safeReadJSON(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch {
-    return null;
-  }
+  // Use cached read for common JSON files
+  const absPath = path.resolve(filePath);
+  return readJSONCached(absPath);
 }
 
 function safeLs(dirPath) {

package/tools/cli/installers/core/installer.js

@@ -11,6 +11,7 @@ const ora = require('ora');
 const yaml = require('js-yaml');
 const { injectContent } = require('../../lib/content-injector');
 const { sha256Hex, toPosixPath, safeTimestampForPath } = require('../../lib/utils');
+const { validatePath, PathValidationError } = require('../../../../lib/validate');
 
 const TEXT_EXTENSIONS = new Set(['.md', '.yaml', '.yml', '.txt', '.json']);
 
@@ -191,6 +192,22 @@ class Installer {
     }
   }
 
+  /**
+   * Validate that a path is within the allowed installation directory.
+   * Prevents path traversal attacks when writing files.
+   *
+   * @param {string} filePath - Path to validate
+   * @param {string} baseDir - Allowed base directory
+   * @throws {PathValidationError} If path escapes base directory
+   */
+  validateInstallPath(filePath, baseDir) {
+    const result = validatePath(filePath, baseDir, { allowSymlinks: false });
+    if (!result.ok) {
+      throw result.error;
+    }
+    return result.resolvedPath;
+  }
+
   /**
    * Copy content from source to destination with placeholder replacement
    * @param {string} source - Source directory
@@ -201,10 +218,16 @@ class Installer {
   async copyContent(source, dest, agileflowFolder, policy = null) {
     const entries = await fs.readdir(source, { withFileTypes: true });
 
+    // Get base directory for validation (agileflowDir from policy or dest itself)
+    const baseDir = policy?.agileflowDir || dest;
+
     for (const entry of entries) {
       const srcPath = path.join(source, entry.name);
       const destPath = path.join(dest, entry.name);
 
+      // Validate destination path to prevent traversal attacks via malicious filenames
+      this.validateInstallPath(destPath, baseDir);
+
       if (entry.isDirectory()) {
         await fs.ensureDir(destPath);
         await this.copyContent(srcPath, destPath, agileflowFolder, policy);
@@ -688,18 +711,25 @@ class Installer {
    * @param {string} srcDir - Source directory
    * @param {string} destDir - Destination directory
    * @param {boolean} force - Overwrite existing files
+   * @param {string} [baseDir] - Base directory for path validation (defaults to destDir on first call)
    */
-  async copyScriptsRecursive(srcDir, destDir, force) {
+  async copyScriptsRecursive(srcDir, destDir, force, baseDir = null) {
     const entries = await fs.readdir(srcDir, { withFileTypes: true });
 
+    // Use destDir as base for validation on first call
+    const validationBase = baseDir || destDir;
+
     for (const entry of entries) {
       const srcPath = path.join(srcDir, entry.name);
       const destPath = path.join(destDir, entry.name);
 
+      // Validate destination path to prevent traversal via malicious filenames
+      this.validateInstallPath(destPath, validationBase);
+
       if (entry.isDirectory()) {
         // Recursively copy subdirectories
         await fs.ensureDir(destPath);
-        await this.copyScriptsRecursive(srcPath, destPath, force);
+        await this.copyScriptsRecursive(srcPath, destPath, force, validationBase);
       } else {
         // Copy file
         const destExists = await fs.pathExists(destPath);

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;
   }
 
   /**