agileflow 3.1.0 → 3.2.1

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

@@ -71,7 +71,8 @@ class BaseIdeSetup {
     });
 
     // Replace standalone "docs" word (not followed by .)
-    result = result.replace(/\bdocs\b(?!\.)/g, this.docsFolder);
+    // Use replacement function to avoid $ in docsFolder being interpreted as regex backreference
+    result = result.replace(/\bdocs\b(?!\.)/g, () => this.docsFolder);
 
     return result;
   }
@@ -371,15 +372,38 @@ class BaseIdeSetup {
   /**
    * 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
    * @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) {
+  async installCommandsRecursive(
+    sourceDir,
+    targetDir,
+    agileflowDir,
+    injectDynamic = false,
+    ideTransform = null
+  ) {
     let commandCount = 0;
     let subdirCount = 0;
 
@@ -419,6 +443,11 @@ class BaseIdeSetup {
           // 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) {
@@ -437,7 +466,8 @@ class BaseIdeSetup {
           sourcePath,
           targetPath,
           agileflowDir,
-          false // Don't inject dynamic content in subdirectories
+          false, // Don't inject dynamic content in subdirectories
+          ideTransform // Pass ideTransform to recursive calls
         );
         commandCount += subResult.commands;
         subdirCount += 1 + subResult.subdirs;

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

@@ -61,12 +61,9 @@ class ClaudeCodeSetup extends BaseIdeSetup {
     // Claude Code specific: Setup damage control hooks
     await this.setupDamageControl(projectDir, agileflowDir, ideDir, options);
 
-    // Claude Code specific: Setup SessionStart hooks (welcome, archive, context-loader, tmux-task-watcher)
+    // Claude Code specific: Setup SessionStart hooks (welcome, archive, context-loader)
     await this.setupSessionStartHooks(projectDir, agileflowDir, ideDir, options);
 
-    // Claude Code specific: Setup Stop hooks (tmux-task-watcher cleanup)
-    await this.setupStopHooks(projectDir, agileflowDir, ideDir, options);
-
     return result;
   }
 
@@ -259,12 +256,6 @@ class ClaudeCodeSetup extends BaseIdeSetup {
           'node $CLAUDE_PROJECT_DIR/.agileflow/scripts/context-loader.js 2>/dev/null || true',
         timeout: 5000,
       },
-      {
-        type: 'command',
-        command:
-          'bash $CLAUDE_PROJECT_DIR/.agileflow/scripts/tmux-task-watcher.sh 2>/dev/null || true',
-        timeout: 5000,
-      },
     ];
 
     // Check if SessionStart hooks already exist
@@ -294,65 +285,7 @@ class ClaudeCodeSetup extends BaseIdeSetup {
 
     // Write settings
     await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
-    console.log(
-      chalk.dim(`    - SessionStart hooks: welcome, archive, context-loader, tmux-task-watcher`)
-    );
-  }
-
-  /**
-   * Setup Stop hooks (tmux-task-watcher cleanup)
-   * @param {string} projectDir - Project directory
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @param {string} claudeDir - .claude directory path
-   * @param {Object} options - Setup options
-   */
-  async setupStopHooks(projectDir, agileflowDir, claudeDir, options = {}) {
-    const settingsPath = path.join(claudeDir, 'settings.json');
-    let settings = {};
-
-    if (fs.existsSync(settingsPath)) {
-      try {
-        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-      } catch (e) {
-        settings = {};
-      }
-    }
-
-    if (!settings.hooks) settings.hooks = {};
-    if (!settings.hooks.Stop) settings.hooks.Stop = [];
-
-    const stopHooks = [
-      {
-        type: 'command',
-        command:
-          'bash $CLAUDE_PROJECT_DIR/.agileflow/scripts/tmux-task-watcher.sh stop 2>/dev/null || true',
-        timeout: 3000,
-      },
-    ];
-
-    const existingEntry = settings.hooks.Stop.find(
-      h => h.matcher === '' || h.matcher === undefined
-    );
-
-    if (existingEntry) {
-      if (!existingEntry.hooks) existingEntry.hooks = [];
-      for (const newHook of stopHooks) {
-        const alreadyExists = existingEntry.hooks.some(
-          h => h.command && h.command.includes('tmux-task-watcher')
-        );
-        if (!alreadyExists) {
-          existingEntry.hooks.push(newHook);
-        }
-      }
-    } else {
-      settings.hooks.Stop.push({
-        matcher: '',
-        hooks: stopHooks,
-      });
-    }
-
-    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
-    console.log(chalk.dim(`    - Stop hooks: tmux-task-watcher cleanup`));
+    console.log(chalk.dim(`    - SessionStart hooks: welcome, archive, context-loader`));
   }
 
   /**

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

@@ -1,13 +1,13 @@
 /**
- * AgileFlow CLI - OpenAI Codex CLI Installer
+ * AgileFlow CLI - OpenAI Codex Installer
  *
- * Installs AgileFlow for OpenAI Codex CLI:
+ * Installs AgileFlow for OpenAI Codex:
  * - Agents become Codex Skills (.codex/skills/agileflow-NAME/)
  * - Commands become Codex Prompts (~/.codex/prompts/agileflow-NAME.md)
  * - AGENTS.md provides project instructions at repo root
  *
  * @see https://developers.openai.com/codex/
- * @see ADR-0002: Codex CLI Integration Strategy
+ * @see ADR-0002: OpenAI Codex Integration Strategy
  */
 
 const path = require('node:path');
@@ -24,11 +24,11 @@ const {
 } = require('../../lib/content-transformer');
 
 /**
- * OpenAI Codex CLI setup handler
+ * OpenAI Codex setup handler
  */
 class CodexSetup extends BaseIdeSetup {
   constructor() {
-    super('codex', 'OpenAI Codex CLI', false);
+    super('codex', 'OpenAI Codex', false);
     // Per-repo config directory
     this.configDir = '.codex';
     // User-level Codex home (can be overridden by $CODEX_HOME)
@@ -44,12 +44,12 @@ class CodexSetup extends BaseIdeSetup {
   }
 
   /**
-   * Detect if Codex CLI is installed/configured
+   * Detect if OpenAI Codex is installed/configured
    * @param {string} projectDir - Project directory
    * @returns {Promise<boolean>}
    */
   async detect(projectDir) {
-    // Check if Codex home exists (user has Codex CLI)
+    // Check if Codex home exists (user has OpenAI Codex)
     const codexHomeExists = await this.exists(this.codexHome);
     // Check if project has .codex/ or AGENTS.md
     const projectCodexExists = await this.exists(path.join(projectDir, this.configDir));
@@ -229,7 +229,7 @@ ${codexHeader}${bodyContent}`;
 
     const content = `# AGENTS.md
 
-> Project instructions for Codex CLI with AgileFlow integration
+> Project instructions for OpenAI Codex with AgileFlow integration
 
 ## Project Commands
 
@@ -334,7 +334,7 @@ This directory contains: [describe purpose]
   }
 
   /**
-   * Setup Codex CLI configuration
+   * Setup OpenAI Codex configuration
    * @param {string} projectDir - Project directory
    * @param {string} agileflowDir - AgileFlow installation directory
    * @param {Object} options - Setup options

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

@@ -1,8 +1,11 @@
 /**
  * AgileFlow CLI - Cursor IDE Installer
  *
- * Installs AgileFlow commands for Cursor IDE.
- * Cursor uses plain Markdown files in .cursor/commands/
+ * Installs AgileFlow commands, agents, and hooks for Cursor IDE.
+ * Cursor uses:
+ * - Plain Markdown files in .cursor/commands/ for slash commands
+ * - Markdown files in .cursor/agents/ for subagents (with YAML frontmatter)
+ * - .cursor/hooks.json for lifecycle hooks
  */
 
 const path = require('node:path');
@@ -27,10 +30,162 @@ class CursorSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, agileflowDir, options = {}) {
-    return this.setupStandard(projectDir, agileflowDir, {
+    // Use standard setup for commands and agents
+    const result = await this.setupStandard(projectDir, agileflowDir, {
       targetSubdir: this.commandsDir,
       agileflowFolder: 'AgileFlow',
     });
+
+    const { ideDir, agileflowTargetDir } = result;
+    const agentsSource = path.join(agileflowDir, 'agents');
+
+    // Cursor specific: Install agents as spawnable subagents (.cursor/agents/AgileFlow/)
+    // This allows Cursor's async subagent spawning feature
+    const spawnableAgentsDir = path.join(ideDir, 'agents', 'AgileFlow');
+
+    // Clean existing spawnable agents directory to prevent duplicates during update
+    if (await fs.pathExists(spawnableAgentsDir)) {
+      await fs.remove(spawnableAgentsDir);
+    }
+
+    const agentInstallResult = await this.installCommandsRecursive(
+      agentsSource,
+      spawnableAgentsDir,
+      agileflowDir,
+      false
+    );
+    console.log(chalk.dim(`    - Spawnable agents: .cursor/agents/AgileFlow/`));
+
+    // Cursor specific: Setup damage control hooks
+    await this.setupDamageControlHooks(projectDir, agileflowDir, ideDir, options);
+
+    return {
+      ...result,
+      agents: agentInstallResult.commands,
+    };
+  }
+
+  /**
+   * Setup damage control hooks for Cursor
+   * Maps Claude Code's PreToolUse hooks to Cursor's lifecycle events:
+   * - beforeShellExecution (for bash commands)
+   * - afterFileEdit (for file edits)
+   *
+   * @param {string} projectDir - Project directory
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @param {string} cursorDir - .cursor directory path
+   * @param {Object} options - Setup options
+   */
+  async setupDamageControlHooks(projectDir, agileflowDir, cursorDir, options = {}) {
+    if (options.skipDamageControl) {
+      return;
+    }
+
+    const hooksPath = path.join(cursorDir, 'hooks.json');
+    let hooks = [];
+
+    // Load existing hooks if they exist
+    if (fs.existsSync(hooksPath)) {
+      try {
+        const content = await fs.readFile(hooksPath, 'utf8');
+        hooks = JSON.parse(content);
+        if (!Array.isArray(hooks)) {
+          hooks = [];
+        }
+      } catch (e) {
+        hooks = [];
+      }
+    }
+
+    // Define damage control hooks for Cursor
+    // Cursor's hooks.json format: Array of {event, command, args, order}
+    const damageControlHooks = [
+      {
+        event: 'beforeShellExecution',
+        command: 'node',
+        args: ['$CURSOR_PROJECT_DIR/.cursor/hooks/damage-control/bash-tool-damage-control.js'],
+        order: 1,
+      },
+      {
+        event: 'afterFileEdit',
+        command: 'node',
+        args: ['$CURSOR_PROJECT_DIR/.cursor/hooks/damage-control/edit-tool-damage-control.js'],
+        order: 1,
+      },
+    ];
+
+    // Check if damage control hooks already exist and merge
+    let hasUpdates = false;
+    for (const newHook of damageControlHooks) {
+      const existingIdx = hooks.findIndex(
+        h =>
+          h.event === newHook.event &&
+          h.command === newHook.command &&
+          (h.args?.join(' ') === newHook.args?.join(' ') ||
+            (h.args && h.args.some(arg => arg.includes('damage-control'))))
+      );
+
+      if (existingIdx === -1) {
+        hooks.push(newHook);
+        hasUpdates = true;
+      }
+    }
+
+    // Only write if we have updates or if file didn't exist
+    if (hasUpdates || !fs.existsSync(hooksPath)) {
+      await fs.ensureDir(path.dirname(hooksPath));
+      await fs.writeFile(hooksPath, JSON.stringify(hooks, null, 2));
+      console.log(chalk.dim(`    - Damage control: hooks enabled`));
+    }
+
+    // Copy damage control scripts
+    await this.setupDamageControlScripts(agileflowDir, cursorDir);
+  }
+
+  /**
+   * Copy damage control scripts to .cursor/hooks/damage-control/
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @param {string} cursorDir - .cursor directory path
+   */
+  async setupDamageControlScripts(agileflowDir, cursorDir) {
+    const damageControlSource = path.join(agileflowDir, 'scripts', 'damage-control');
+    const damageControlTarget = path.join(cursorDir, 'hooks', 'damage-control');
+
+    if (!fs.existsSync(damageControlSource)) {
+      return;
+    }
+
+    await this.ensureDir(damageControlTarget);
+
+    // Copy hook scripts
+    const scripts = [
+      'bash-tool-damage-control.js',
+      'edit-tool-damage-control.js',
+      'write-tool-damage-control.js',
+    ];
+
+    for (const script of scripts) {
+      const src = path.join(damageControlSource, script);
+      const dest = path.join(damageControlTarget, script);
+      if (fs.existsSync(src)) {
+        await fs.copy(src, dest);
+      }
+    }
+
+    // Copy lib/damage-control-utils.js (required by hook scripts)
+    const libSource = path.join(agileflowDir, 'scripts', 'lib', 'damage-control-utils.js');
+    const libTarget = path.join(cursorDir, 'hooks', 'lib', 'damage-control-utils.js');
+    if (fs.existsSync(libSource)) {
+      await this.ensureDir(path.dirname(libTarget));
+      await fs.copy(libSource, libTarget);
+    }
+
+    // Copy patterns.yaml (preserve existing)
+    const patternsSource = path.join(damageControlSource, 'patterns.yaml');
+    const patternsTarget = path.join(damageControlTarget, 'patterns.yaml');
+    if (fs.existsSync(patternsSource) && !fs.existsSync(patternsTarget)) {
+      await fs.copy(patternsSource, patternsTarget);
+    }
   }
 
   /**
@@ -45,11 +200,17 @@ class CursorSetup extends BaseIdeSetup {
       console.log(chalk.dim(`    Removed old AgileFlow rules from ${this.displayName}`));
     }
 
-    // Remove .cursor/commands/agileflow (for re-installation)
+    // Remove .cursor/commands/AgileFlow (for re-installation)
     const commandsPath = path.join(projectDir, this.configDir, this.commandsDir, 'AgileFlow');
     if (await this.exists(commandsPath)) {
       await fs.remove(commandsPath);
     }
+
+    // Remove .cursor/agents/AgileFlow (for re-installation)
+    const agentsPath = path.join(projectDir, this.configDir, 'agents', 'AgileFlow');
+    if (await this.exists(agentsPath)) {
+      await fs.remove(agentsPath);
+    }
   }
 }