agileflow 2.91.0 → 2.92.1

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

@@ -164,6 +164,10 @@ class Installer {
       spinner.text = 'Installing changelog...';
       await this.installChangelog(agileflowDir, { force: effectiveForce });
 
+      // Set up shell aliases for claude command
+      spinner.text = 'Setting up shell aliases...';
+      const aliasResult = await this.setupShellAliases(directory, { force: effectiveForce });
+
       // Create config.yaml
       spinner.text = 'Creating configuration...';
       await this.createConfig(agileflowDir, userName, agileflowFolder, { force: effectiveForce });
@@ -191,6 +195,7 @@ class Installer {
         projectDir: directory,
         counts,
         fileOps,
+        shellAliases: aliasResult,
       };
     } catch (error) {
       spinner.fail('Installation failed');
@@ -813,6 +818,95 @@ class Installer {
     }
   }
 
+  /**
+   * Set up shell aliases for the claude command
+   * Adds aliases to ~/.bashrc and/or ~/.zshrc so 'claude' auto-spawns tmux
+   * @param {string} directory - Project directory (used for relative path in alias)
+   * @param {Object} options - Setup options
+   * @param {boolean} options.force - Overwrite existing aliases
+   * @returns {Promise<Object>} Result with shells configured
+   */
+  async setupShellAliases(directory, options = {}) {
+    const os = require('os');
+    const result = {
+      configured: [],
+      skipped: [],
+      error: null,
+    };
+
+    // Only set up aliases on Unix-like systems
+    if (process.platform === 'win32') {
+      result.skipped.push('Windows (not supported)');
+      return result;
+    }
+
+    const homeDir = os.homedir();
+    const aliasBlock = `
+# AgileFlow tmux wrapper
+# Use 'af' or 'agileflow' for tmux, 'claude' stays normal
+alias af="bash .agileflow/scripts/af"
+alias agileflow="bash .agileflow/scripts/af"
+`;
+
+    const marker = '# AgileFlow tmux wrapper';
+    const rcFiles = [
+      { name: 'bash', path: path.join(homeDir, '.bashrc') },
+      { name: 'zsh', path: path.join(homeDir, '.zshrc') },
+    ];
+
+    for (const rc of rcFiles) {
+      try {
+        // Check if RC file exists
+        if (!(await fs.pathExists(rc.path))) {
+          result.skipped.push(`${rc.name} (no ${path.basename(rc.path)})`);
+          continue;
+        }
+
+        const content = await fs.readFile(rc.path, 'utf8');
+
+        // Check if aliases already exist
+        if (content.includes(marker)) {
+          if (options.force) {
+            // Remove existing block and re-add
+            const lines = content.split('\n');
+            const filteredLines = [];
+            let inBlock = false;
+
+            for (const line of lines) {
+              if (line.includes(marker)) {
+                inBlock = true;
+                continue;
+              }
+              if (inBlock && line.startsWith('alias ')) {
+                continue;
+              }
+              if (inBlock && line.trim() === '') {
+                inBlock = false;
+                continue;
+              }
+              inBlock = false;
+              filteredLines.push(line);
+            }
+
+            await fs.writeFile(rc.path, filteredLines.join('\n') + aliasBlock, 'utf8');
+            result.configured.push(rc.name);
+          } else {
+            result.skipped.push(`${rc.name} (already configured)`);
+          }
+          continue;
+        }
+
+        // Append aliases to RC file
+        await fs.appendFile(rc.path, aliasBlock);
+        result.configured.push(rc.name);
+      } catch (err) {
+        result.skipped.push(`${rc.name} (error: ${err.message})`);
+      }
+    }
+
+    return result;
+  }
+
   /**
    * Get installation status
    * @param {string} directory - Project directory

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

@@ -15,6 +15,11 @@ const {
   ContentInjectionError,
   withPermissionHandling,
 } = require('../../lib/ide-errors');
+const {
+  replaceReferences,
+  createDocsReplacements,
+  injectContent: injectDynamicContentHelper,
+} = require('../../lib/content-transformer');
 
 /**
  * Base class for IDE-specific setup
@@ -48,6 +53,7 @@ class BaseIdeSetup {
 
   /**
    * 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
    */
@@ -56,28 +62,31 @@ class BaseIdeSetup {
       return content; // No replacement needed
     }
 
-    // Replace all variations of docs/ references
-    return content
-      .replace(/docs\//g, `${this.docsFolder}/`)
-      .replace(/`docs\//g, `\`${this.docsFolder}/`)
-      .replace(/"docs\//g, `"${this.docsFolder}/`)
-      .replace(/'docs\//g, `'${this.docsFolder}/`)
-      .replace(/\(docs\//g, `(${this.docsFolder}/`)
-      .replace(/docs\/\)/g, `${this.docsFolder}/)`)
-      .replace(/\bdocs\b(?!\.)/g, this.docsFolder); // Replace standalone "docs" word
+    // 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 .)
+    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
    * @returns {string} Content with placeholders replaced
    */
   injectDynamicContent(content, agileflowDir) {
-    const { injectContent } = require('../../lib/content-injector');
     // agileflowDir is the user's .agileflow installation directory
     // which has agents/, commands/, skills/ at the root level
-    return injectContent(content, {
+    return injectDynamicContentHelper(content, {
       coreDir: agileflowDir,
       agileflowFolder: this.agileflowFolder,
       version: this.getVersion(),

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

@@ -14,9 +14,14 @@ const path = require('node:path');
 const os = require('node:os');
 const fs = require('fs-extra');
 const chalk = require('chalk');
-const { safeLoad, yaml } = require('../../../../lib/yaml-utils');
+const { yaml } = require('../../../../lib/yaml-utils');
 const { BaseIdeSetup } = require('./_base-ide');
-const { parseFrontmatter } = require('../../../../scripts/lib/frontmatter-parser');
+const {
+  getFrontmatter,
+  stripFrontmatter,
+  replaceReferences,
+  IDE_REPLACEMENTS,
+} = require('../../lib/content-transformer');
 
 /**
  * OpenAI Codex CLI setup handler
@@ -55,24 +60,15 @@ class CodexSetup extends BaseIdeSetup {
 
   /**
    * Convert an AgileFlow agent markdown file to Codex SKILL.md format
+   * Uses content-transformer module for consistent transformations
    * @param {string} content - Original agent markdown content
    * @param {string} agentName - Agent name (e.g., 'database')
    * @returns {string} Codex SKILL.md content
    */
   convertAgentToSkill(content, agentName) {
-    // Extract frontmatter using shared parser
-    let description = `AgileFlow ${agentName} agent`;
-    let model = 'default';
-
-    const frontmatter = parseFrontmatter(content);
-    if (frontmatter && Object.keys(frontmatter).length > 0) {
-      if (frontmatter.description) {
-        description = frontmatter.description;
-      }
-      if (frontmatter.model) {
-        model = frontmatter.model;
-      }
-    }
+    // Extract frontmatter using content-transformer
+    const frontmatter = getFrontmatter(content);
+    const description = frontmatter.description || `AgileFlow ${agentName} agent`;
 
     // Create SKILL.md with YAML frontmatter
     const skillFrontmatter = yaml
@@ -83,8 +79,8 @@ class CodexSetup extends BaseIdeSetup {
       })
       .trim();
 
-    // Remove original frontmatter from content
-    let bodyContent = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+    // Remove original frontmatter from content using content-transformer
+    let bodyContent = stripFrontmatter(content);
 
     // Add Codex-specific header
     const codexHeader = `# AgileFlow: ${agentName.charAt(0).toUpperCase() + agentName.slice(1)} Agent
@@ -93,12 +89,8 @@ class CodexSetup extends BaseIdeSetup {
 
 `;
 
-    // Replace Claude-specific references
-    bodyContent = bodyContent
-      .replace(/Claude Code/gi, 'Codex CLI')
-      .replace(/CLAUDE\.md/g, 'AGENTS.md')
-      .replace(/\.claude\//g, '.codex/')
-      .replace(/Task tool/gi, 'skill invocation');
+    // Replace Claude-specific references using content-transformer
+    bodyContent = replaceReferences(bodyContent, IDE_REPLACEMENTS.codex);
 
     return `---
 ${skillFrontmatter}
@@ -109,35 +101,25 @@ ${codexHeader}${bodyContent}`;
 
   /**
    * Convert an AgileFlow command markdown file to Codex prompt format
+   * Uses content-transformer module for consistent transformations
    * @param {string} content - Original command markdown content
    * @param {string} commandName - Command name (e.g., 'board')
    * @returns {string} Codex prompt content
    */
   convertCommandToPrompt(content, commandName) {
-    // Extract description from frontmatter if present
-    let description = `AgileFlow ${commandName} command`;
-
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    if (frontmatterMatch) {
-      try {
-        const frontmatter = safeLoad(frontmatterMatch[1]);
-        if (frontmatter.description) {
-          description = frontmatter.description;
-        }
-      } catch (e) {
-        // Ignore YAML parse errors
-      }
-    }
-
-    // Remove original frontmatter from content
-    let bodyContent = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
-
-    // Replace Claude-specific references
-    bodyContent = bodyContent
-      .replace(/Claude Code/gi, 'Codex CLI')
-      .replace(/CLAUDE\.md/g, 'AGENTS.md')
-      .replace(/\.claude\//g, '.codex/')
-      .replace(/\/agileflow:/g, '$agileflow-');
+    // Extract description from frontmatter using content-transformer
+    const frontmatter = getFrontmatter(content);
+    const description = frontmatter.description || `AgileFlow ${commandName} command`;
+
+    // Remove original frontmatter from content using content-transformer
+    let bodyContent = stripFrontmatter(content);
+
+    // Replace Claude-specific references using content-transformer
+    // Use codex replacements plus command-specific pattern
+    bodyContent = replaceReferences(bodyContent, {
+      ...IDE_REPLACEMENTS.codex,
+      '/agileflow:': '$agileflow-',
+    });
 
     // Add Codex prompt header
     const header = `# AgileFlow: ${commandName}

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

@@ -15,7 +15,7 @@ const { BaseIdeSetup } = require('./_base-ide');
  */
 class WindsurfSetup extends BaseIdeSetup {
   constructor() {
-    super('windsurf', 'Windsurf', true);
+    super('windsurf', 'Windsurf', false);
     this.configDir = '.windsurf';
     this.workflowsDir = 'workflows';
   }

package/tools/cli/lib/config-manager.js

@@ -13,6 +13,7 @@
 const path = require('path');
 const fs = require('fs-extra');
 const { safeLoad, safeDump } = require('../../../lib/yaml-utils');
+const { hasUnsafePathPatterns } = require('../../../lib/validate-paths');
 
 /**
  * Configuration schema definition
@@ -50,13 +51,27 @@ const CONFIG_SCHEMA = {
     type: 'string',
     default: '.agileflow',
     required: true,
-    validate: v => typeof v === 'string' && v.length > 0 && !v.includes('..'),
+    // Security: Use proper path validation instead of simple string check
+    validate: v => {
+      if (typeof v !== 'string' || v.length === 0) return false;
+      // Must be a relative path without unsafe patterns
+      if (path.isAbsolute(v)) return false;
+      const check = hasUnsafePathPatterns(v);
+      return check.safe;
+    },
   },
   docsFolder: {
     type: 'string',
     default: 'docs',
     required: true,
-    validate: v => typeof v === 'string' && v.length > 0 && !v.includes('..'),
+    // Security: Use proper path validation instead of simple string check
+    validate: v => {
+      if (typeof v !== 'string' || v.length === 0) return false;
+      // Must be a relative path without unsafe patterns
+      if (path.isAbsolute(v)) return false;
+      const check = hasUnsafePathPatterns(v);
+      return check.safe;
+    },
   },
   installedAt: {
     type: 'string',

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

@@ -0,0 +1,271 @@
+/**
+ * content-transformer.js - Reusable content transformation utilities
+ *
+ * Extracts common content transformation patterns from IDE installers:
+ * - replaceReferences: Generic string replacement with pattern support
+ * - stripFrontmatter: Remove YAML frontmatter from content
+ * - convertFrontmatter: Transform frontmatter keys/values between formats
+ * - injectContent: Delegate to existing content-injector
+ *
+ * Created as part of US-0177: Extract content transformation into reusable helper module
+ */
+
+const { parseFrontmatter, extractBody } = require('../../../scripts/lib/frontmatter-parser');
+
+/**
+ * Replace multiple string patterns in content
+ *
+ * @param {string} content - The content to transform
+ * @param {Object|Array} replacements - Either an object of {pattern: replacement} pairs,
+ *                                      or an array of {pattern, replacement, flags} objects
+ * @returns {string} Content with all replacements applied
+ *
+ * @example
+ * // Object form (simple string replacement)
+ * replaceReferences(content, {
+ *   'Claude Code': 'Codex CLI',
+ *   '.claude/': '.codex/',
+ *   'CLAUDE.md': 'AGENTS.md'
+ * });
+ *
+ * @example
+ * // Array form (with regex flags)
+ * replaceReferences(content, [
+ *   { pattern: 'Claude Code', replacement: 'Codex CLI', flags: 'gi' },
+ *   { pattern: /\.claude\//g, replacement: '.codex/' }
+ * ]);
+ */
+function replaceReferences(content, replacements) {
+  if (!content || typeof content !== 'string') {
+    return content || '';
+  }
+
+  let result = content;
+
+  if (Array.isArray(replacements)) {
+    // Array form: [{pattern, replacement, flags?}]
+    for (const item of replacements) {
+      if (!item || !item.pattern) continue;
+
+      let regex;
+      if (item.pattern instanceof RegExp) {
+        regex = item.pattern;
+      } else {
+        const flags = item.flags || 'g';
+        regex = new RegExp(escapeRegex(item.pattern), flags);
+      }
+      result = result.replace(regex, item.replacement || '');
+    }
+  } else if (typeof replacements === 'object' && replacements !== null) {
+    // Object form: {pattern: replacement}
+    for (const [pattern, replacement] of Object.entries(replacements)) {
+      result = result.replace(new RegExp(escapeRegex(pattern), 'g'), replacement);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Escape special regex characters in a string
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for use in RegExp
+ */
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Remove YAML frontmatter from content, returning only the body
+ *
+ * @param {string} content - Content with optional YAML frontmatter
+ * @returns {string} Content body without frontmatter
+ *
+ * @example
+ * const body = stripFrontmatter(`---
+ * title: My Document
+ * ---
+ *
+ * # Heading
+ * Content here`);
+ * // Returns: "# Heading\nContent here"
+ */
+function stripFrontmatter(content) {
+  return extractBody(content);
+}
+
+/**
+ * Convert frontmatter between formats using a mapping configuration
+ *
+ * @param {Object} frontmatter - Parsed frontmatter object
+ * @param {Object} config - Conversion configuration
+ * @param {Object} [config.keyMap] - Map of source keys to target keys
+ * @param {Object} [config.valueMap] - Map of key names to value transformation functions
+ * @param {Array} [config.include] - Only include these keys (whitelist)
+ * @param {Array} [config.exclude] - Exclude these keys (blacklist)
+ * @param {Object} [config.defaults] - Default values to add if not present
+ * @returns {Object} Transformed frontmatter object
+ *
+ * @example
+ * const converted = convertFrontmatter(
+ *   { name: 'security', description: 'Security agent', tools: ['Read', 'Write'] },
+ *   {
+ *     keyMap: { name: 'skill_name', tools: 'allowed_tools' },
+ *     valueMap: { description: (v) => v.replace('agent', 'skill') },
+ *     exclude: ['internal_only'],
+ *     defaults: { version: '1.0' }
+ *   }
+ * );
+ */
+function convertFrontmatter(frontmatter, config = {}) {
+  if (!frontmatter || typeof frontmatter !== 'object') {
+    return {};
+  }
+
+  const { keyMap = {}, valueMap = {}, include, exclude = [], defaults = {} } = config;
+
+  const result = { ...defaults };
+
+  for (const [key, value] of Object.entries(frontmatter)) {
+    // Skip excluded keys
+    if (exclude.includes(key)) continue;
+
+    // Skip if not in include list (when include is specified)
+    if (include && !include.includes(key)) continue;
+
+    // Map key name if mapping exists
+    const targetKey = keyMap[key] || key;
+
+    // Transform value if transformation exists
+    const targetValue = valueMap[key] ? valueMap[key](value) : value;
+
+    result[targetKey] = targetValue;
+  }
+
+  return result;
+}
+
+/**
+ * Inject dynamic content into a template using content-injector
+ *
+ * @param {string} content - Content with placeholders
+ * @param {Object} options - Injection options
+ * @param {string} options.coreDir - Path to AgileFlow core directory
+ * @param {string} [options.agileflowFolder] - Target AgileFlow folder name (default: '.agileflow')
+ * @param {string} [options.version] - Version string to inject
+ * @returns {string} Content with placeholders replaced
+ */
+function injectContent(content, options) {
+  const { injectContent: inject } = require('./content-injector');
+  return inject(content, options);
+}
+
+/**
+ * Parse frontmatter from content
+ * Re-exported from frontmatter-parser for convenience
+ *
+ * @param {string} content - Content with YAML frontmatter
+ * @returns {Object} Parsed frontmatter as object
+ */
+function getFrontmatter(content) {
+  return parseFrontmatter(content);
+}
+
+/**
+ * Common replacement patterns for IDE conversions
+ */
+const IDE_REPLACEMENTS = {
+  /**
+   * Claude Code to Codex CLI conversions
+   */
+  codex: {
+    'Claude Code': 'Codex CLI',
+    'claude code': 'Codex CLI',
+    CLAUDE_CODE: 'CODEX_CLI',
+    'CLAUDE.md': 'AGENTS.md',
+    '.claude/': '.codex/',
+    '.claude\\': '.codex\\',
+    'Task tool': 'skill invocation',
+    'Task agent': 'skill invocation',
+  },
+
+  /**
+   * Claude Code to Cursor conversions
+   */
+  cursor: {
+    'Claude Code': 'Cursor',
+    'claude code': 'Cursor',
+    '.claude/': '.cursor/',
+    '.claude\\': '.cursor\\',
+  },
+
+  /**
+   * Claude Code to Windsurf conversions
+   */
+  windsurf: {
+    'Claude Code': 'Windsurf',
+    'claude code': 'Windsurf',
+    '.claude/': '.windsurf/',
+    '.claude\\': '.windsurf\\',
+  },
+};
+
+/**
+ * Create docs folder reference replacements
+ *
+ * @param {string} targetFolder - Target docs folder name (e.g., 'project-docs')
+ * @returns {Object} Replacement patterns for docs references
+ */
+function createDocsReplacements(targetFolder) {
+  if (targetFolder === 'docs') {
+    return {}; // No changes needed
+  }
+
+  return {
+    'docs/': `${targetFolder}/`,
+    '`docs/': `\`${targetFolder}/`,
+    '"docs/': `"${targetFolder}/`,
+    "'docs/": `'${targetFolder}/`,
+    '(docs/': `(${targetFolder}/`,
+    '[docs/': `[${targetFolder}/`,
+  };
+}
+
+/**
+ * Transform content for a specific IDE target
+ *
+ * @param {string} content - Source content
+ * @param {string} targetIde - Target IDE: 'codex', 'cursor', 'windsurf'
+ * @param {Object} [options] - Additional options
+ * @param {string} [options.docsFolder] - Custom docs folder name
+ * @param {Object} [options.additionalReplacements] - Extra replacements to apply
+ * @returns {string} Transformed content
+ */
+function transformForIde(content, targetIde, options = {}) {
+  const { docsFolder, additionalReplacements = {} } = options;
+
+  // Start with IDE-specific replacements
+  const replacements = { ...(IDE_REPLACEMENTS[targetIde] || {}) };
+
+  // Add docs folder replacements if needed
+  if (docsFolder && docsFolder !== 'docs') {
+    Object.assign(replacements, createDocsReplacements(docsFolder));
+  }
+
+  // Add any additional custom replacements
+  Object.assign(replacements, additionalReplacements);
+
+  return replaceReferences(content, replacements);
+}
+
+module.exports = {
+  replaceReferences,
+  stripFrontmatter,
+  convertFrontmatter,
+  injectContent,
+  getFrontmatter,
+  escapeRegex,
+  IDE_REPLACEMENTS,
+  createDocsReplacements,
+  transformForIde,
+};

package/tools/cli/lib/error-handler.js

@@ -7,9 +7,15 @@
  * - CRITICAL: Severe errors (exit 1 + stack trace if DEBUG=1)
  *
  * Error output format: "X <problem> | Action: <what to do> | Run: <command>"
+ *
+ * Note: Formatting logic is extracted to lib/format-error.js for standalone use.
  */
 
-const { c } = require('../../../lib/colors');
+const {
+  formatError: formatErrorHelper,
+  formatWarning: formatWarningHelper,
+  formatErrorWithStack,
+} = require('../../../lib/format-error');
 
 class ErrorHandler {
   /**
@@ -30,14 +36,7 @@ class ErrorHandler {
    * @returns {string} Formatted error string
    */
   formatError(message, actionText, commandHint) {
-    let output = `${c.red}\u2716${c.reset} ${message}`;
-    if (actionText) {
-      output += ` ${c.dim}|${c.reset} ${c.cyan}Action:${c.reset} ${actionText}`;
-    }
-    if (commandHint) {
-      output += ` ${c.dim}|${c.reset} ${c.green}Run:${c.reset} ${c.bold}${commandHint}${c.reset}`;
-    }
-    return output;
+    return formatErrorHelper(message, actionText, commandHint);
   }
 
   /**
@@ -48,14 +47,7 @@ class ErrorHandler {
    * @returns {string} Formatted warning string
    */
   formatWarning(message, actionText, commandHint) {
-    let output = `${c.yellow}\u26A0${c.reset}  ${message}`;
-    if (actionText) {
-      output += ` ${c.dim}|${c.reset} ${c.cyan}Action:${c.reset} ${actionText}`;
-    }
-    if (commandHint) {
-      output += ` ${c.dim}|${c.reset} ${c.green}Run:${c.reset} ${c.bold}${commandHint}${c.reset}`;
-    }
-    return output;
+    return formatWarningHelper(message, actionText, commandHint);
   }
 
   /**
@@ -94,11 +86,11 @@ class ErrorHandler {
    * @param {Error} [error] - Original error object for stack trace
    */
   critical(message, actionText, commandHint, error) {
-    console.error(this.formatError(message, actionText, commandHint));
-    if (process.env.DEBUG === '1' && error?.stack) {
-      console.error(`\n${c.dim}Stack trace:${c.reset}`);
-      console.error(c.dim + error.stack + c.reset);
-    }
+    const formatted = formatErrorWithStack(message, error, {
+      action: actionText,
+      command: commandHint,
+    });
+    console.error(formatted);
     process.exit(1);
   }