agileflow 3.4.2 → 4.0.0-alpha.1

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

@@ -1,357 +0,0 @@
-/**
- * ide-generator.js - Build-time IDE-specific prompt/skill/agent generator
- *
- * Integrates IDE capability profiles with content transformer to produce
- * IDE-native commands and agents during the install process.
- *
- * Main entry points:
- * - generateForIde(content, targetIde, options) - Base transformation
- * - generateCommandForIde(content, commandName, targetIde, options) - Command-specific
- * - generateAgentForIde(content, agentName, targetIde, options) - Agent-specific
- */
-
-const {
-  transformForIde,
-  transformToolReferences,
-  replaceReferences,
-  stripFrontmatter,
-  getFrontmatter,
-  convertFrontmatter,
-} = require('./content-transformer');
-
-// Lazy-load profile loader - only if profiles are needed
-let profileLoader = null;
-
-function getProfileLoader() {
-  if (!profileLoader) {
-    try {
-      profileLoader = require('../../../src/core/profiles/loader');
-    } catch (e) {
-      // Profiles not available - return null to indicate fallback mode
-      return null;
-    }
-  }
-  return profileLoader;
-}
-
-/**
- * Get the IDE prefix style for commands
- * Claude Code uses "/agileflow:", others use "/" or "$" as prefix
- * @param {string} targetIde - Target IDE: 'claude-code', 'cursor', 'windsurf', 'codex'
- * @returns {string} Command prefix pattern
- * @private
- */
-function getCommandPrefix(targetIde) {
-  const prefixes = {
-    'claude-code': '/agileflow:',
-    cursor: '/',
-    windsurf: '/',
-    codex: '$agileflow-',
-  };
-  return prefixes[targetIde] || '/agileflow:';
-}
-
-/**
- * Convert /agileflow:style:commands to IDE-specific format
- * - Claude Code: /agileflow:foo:bar → /agileflow:foo:bar (unchanged)
- * - Cursor: /agileflow:foo:bar → /foo-bar
- * - Windsurf: /agileflow:foo:bar → /agileflow-foo-bar
- * - Codex: /agileflow:foo:bar → $agileflow-foo-bar
- *
- * @param {string} content - Content with command references
- * @param {string} targetIde - Target IDE
- * @returns {string} Content with converted command prefixes
- * @private
- */
-function convertCommandPrefixes(content, targetIde) {
-  if (targetIde === 'claude-code') {
-    return content; // No conversion needed
-  }
-
-  let result = content;
-
-  if (targetIde === 'cursor') {
-    // /agileflow:foo:bar → /foo-bar
-    result = result.replace(/\/agileflow:([a-zA-Z0-9:_-]+)/g, (_match, rest) => {
-      return '/' + rest.replace(/:/g, '-');
-    });
-  } else if (targetIde === 'windsurf') {
-    // /agileflow:foo:bar → /agileflow-foo-bar
-    result = result.replace(/\/agileflow:([a-zA-Z0-9:_-]+)/g, (_match, rest) => {
-      return '/agileflow-' + rest.replace(/:/g, '-');
-    });
-  } else if (targetIde === 'codex') {
-    // /agileflow:foo:bar → $agileflow-foo-bar
-    result = result.replace(/\/agileflow:([a-zA-Z0-9:_-]+)/g, (_match, rest) => {
-      return '$agileflow-' + rest.replace(/:/g, '-');
-    });
-  }
-
-  return result;
-}
-
-/**
- * Main entry point for IDE-specific content generation
- * Takes canonical Claude Code markdown content and transforms it for a target IDE
- *
- * @param {string} content - Source content (Claude Code format)
- * @param {string} targetIde - Target IDE: 'claude-code', 'cursor', 'windsurf', 'codex'
- * @param {Object} [options] - Generation options
- * @param {string} [options.docsFolder] - Custom docs folder name
- * @param {boolean} [options.transformTools] - Apply tool reference transformations (default: true)
- * @param {boolean} [options.transformPrefixes] - Convert command prefixes (default: true)
- * @param {Object} [options.additionalReplacements] - Extra IDE-specific replacements
- * @returns {string} Transformed content for target IDE
- *
- * @example
- * const content = await fs.readFile('command.md', 'utf8');
- * const cursorVersion = generateForIde(content, 'cursor', { transformTools: true });
- */
-function generateForIde(content, targetIde, options = {}) {
-  if (!content || typeof content !== 'string') {
-    return content || '';
-  }
-
-  // Claude Code is canonical format - return as-is
-  if (targetIde === 'claude-code') {
-    return content;
-  }
-
-  const {
-    docsFolder,
-    transformTools = true,
-    transformPrefixes = true,
-    additionalReplacements = {},
-  } = options;
-
-  // Step 1: Apply IDE-specific replacements and docs folder updates
-  let result = transformForIde(content, targetIde, {
-    docsFolder,
-    additionalReplacements,
-    transformTools: false, // Will apply separately
-  });
-
-  // Step 2: Apply tool reference transformations if requested
-  if (transformTools) {
-    result = transformToolReferences(result, targetIde);
-  }
-
-  // Step 3: Convert command prefixes if requested
-  if (transformPrefixes) {
-    result = convertCommandPrefixes(result, targetIde);
-  }
-
-  return result;
-}
-
-/**
- * Generate IDE-specific command content with IDE-native wrapping
- *
- * For Codex, adds {{input}} placeholder at end for context injection.
- * For other IDEs, uses base generateForIde() transformation.
- *
- * @param {string} content - Source command content (Claude Code format)
- * @param {string} commandName - Command name for display
- * @param {string} targetIde - Target IDE
- * @param {Object} [options] - Generation options (same as generateForIde)
- * @returns {string} IDE-native command content
- *
- * @example
- * const cmd = await fs.readFile('commands/deploy.md', 'utf8');
- * const codexPrompt = generateCommandForIde(cmd, 'deploy', 'codex');
- */
-function generateCommandForIde(content, commandName, targetIde, options = {}) {
-  // Handle null/undefined content
-  if (content === null || content === undefined || typeof content !== 'string') {
-    return '';
-  }
-
-  // Start with base transformation
-  let result = generateForIde(content, targetIde, options);
-
-  // Codex-specific wrapping: Add {{input}} placeholder
-  if (targetIde === 'codex' && result !== '') {
-    // Strip frontmatter for Codex format
-    const bodyContent = stripFrontmatter(result);
-    const frontmatter = getFrontmatter(content);
-    const description = frontmatter.description || `AgileFlow ${commandName} command`;
-
-    const header = `# AgileFlow: ${commandName}
-
-> ${description}
-
-## Instructions
-
-`;
-
-    const footer = `
-
-## Context
-
-{{input}}
-`;
-
-    result = header + bodyContent + footer;
-  }
-
-  return result;
-}
-
-/**
- * Generate IDE-specific agent/skill content
- *
- * Performs IDE-specific transformations including:
- * - For Codex: Converts to SKILL.md format with skill-specific frontmatter
- * - For Windsurf: Converts to agentskills.io format with skill-specific frontmatter
- * - For Cursor: Adds agent-specific frontmatter for spawnable agents
- * - For Claude Code: Returns unchanged (canonical format)
- *
- * @param {string} content - Source agent content (Claude Code format)
- * @param {string} agentName - Agent name (e.g., 'database', 'security')
- * @param {string} targetIde - Target IDE: 'claude-code', 'cursor', 'windsurf', 'codex'
- * @param {Object} [options] - Generation options
- * @param {string} [options.docsFolder] - Custom docs folder name
- * @param {boolean} [options.transformTools] - Apply tool reference transformations (default: true)
- * @returns {string} IDE-native agent/skill content
- *
- * @example
- * const agent = await fs.readFile('agents/security.md', 'utf8');
- * const windsurfSkill = generateAgentForIde(agent, 'security', 'windsurf');
- */
-function generateAgentForIde(content, agentName, targetIde, options = {}) {
-  if (!content || typeof content !== 'string') {
-    return content || '';
-  }
-
-  // Claude Code is canonical format
-  if (targetIde === 'claude-code') {
-    return content;
-  }
-
-  const { docsFolder, transformTools = true } = options;
-
-  // Get base transformations
-  const baseContent = generateForIde(content, targetIde, {
-    docsFolder,
-    transformTools,
-    transformPrefixes: false, // Don't convert prefixes in agent bodies
-  });
-
-  // Extract frontmatter and body
-  const frontmatter = getFrontmatter(content);
-  const description = frontmatter.description || `AgileFlow ${agentName} agent`;
-
-  // Apply IDE-specific formatting
-  if (targetIde === 'codex') {
-    return formatAgentForCodex(baseContent, agentName, description);
-  } else if (targetIde === 'windsurf') {
-    return formatAgentForWindsurf(baseContent, agentName, description);
-  } else if (targetIde === 'cursor') {
-    return formatAgentForCursor(baseContent, agentName, description);
-  }
-
-  return baseContent;
-}
-
-/**
- * Format agent content for Codex SKILL.md format
- * @private
- */
-function formatAgentForCodex(content, agentName, description) {
-  const yaml = require('../../../lib/yaml-utils').yaml;
-
-  const bodyContent = stripFrontmatter(content);
-
-  // Create SKILL.md with YAML frontmatter
-  const skillFrontmatter = yaml
-    .dump({
-      name: `agileflow-${agentName}`,
-      description: description,
-      version: '1.0.0',
-    })
-    .trim();
-
-  const codexHeader = `# AgileFlow: ${agentName.charAt(0).toUpperCase() + agentName.slice(1)} Agent
-
-> Invoke with \`$agileflow-${agentName}\` or via \`/skills\`
-
-`;
-
-  return `---
-${skillFrontmatter}
----
-
-${codexHeader}${bodyContent}`;
-}
-
-/**
- * Format agent content for Windsurf SKILL.md (agentskills.io spec)
- * @private
- */
-function formatAgentForWindsurf(content, agentName, description) {
-  const yaml = require('../../../lib/yaml-utils').yaml;
-
-  const bodyContent = stripFrontmatter(content);
-
-  // Create SKILL.md with YAML frontmatter (agentskills.io spec)
-  const skillFrontmatter = yaml
-    .dump({
-      name: `agileflow-${agentName}`,
-      description: description,
-    })
-    .trim();
-
-  const windsurfHeader = `# AgileFlow: ${agentName.charAt(0).toUpperCase() + agentName.slice(1)} Skill
-
-> Use this skill via \`@agileflow-${agentName}\` or /cascade
-
-`;
-
-  return `---
-${skillFrontmatter}
----
-
-${windsurfHeader}${bodyContent}`;
-}
-
-/**
- * Format agent content for Cursor spawnable agent
- * Cursor agents use YAML frontmatter with name, description, and model fields
- * @private
- */
-function formatAgentForCursor(content, agentName, description) {
-  const yaml = require('../../../lib/yaml-utils').yaml;
-
-  // Extract frontmatter from source
-  const sourceFrontmatter = getFrontmatter(content);
-  const bodyContent = stripFrontmatter(content);
-
-  // Create agent frontmatter for Cursor
-  const agentFrontmatter = yaml
-    .dump({
-      name: `agileflow-${agentName}`,
-      description: description,
-      model: sourceFrontmatter.model || 'claude-3-5-sonnet',
-      readonly: false,
-    })
-    .trim();
-
-  return `---
-${agentFrontmatter}
----
-
-${bodyContent}`;
-}
-
-module.exports = {
-  generateForIde,
-  generateCommandForIde,
-  generateAgentForIde,
-  getCommandPrefix,
-  // Export private functions for testing
-  _convertCommandPrefixes: convertCommandPrefixes,
-  _getProfileLoader: getProfileLoader,
-  _formatAgentForCodex: formatAgentForCodex,
-  _formatAgentForWindsurf: formatAgentForWindsurf,
-  _formatAgentForCursor: formatAgentForCursor,
-};

package/tools/cli/lib/ide-health-monitor.js

@@ -1,364 +0,0 @@
-/**
- * AgileFlow CLI - IDE Health Monitor
- *
- * Monitors IDE detection health with caching and circuit-breaker pattern.
- * Reduces filesystem operations during repeated IDE checks.
- *
- * Features:
- * - LRU cache for IDE detection results (300s TTL by default)
- * - Circuit-breaker pattern to stop checking failing IDEs
- * - Health metrics logging to .agileflow/cache/ide-health.json
- */
-
-const fs = require('fs-extra');
-const path = require('path');
-
-/**
- * IDE Health Monitor - Caching and circuit-breaker for IDE detection
- */
-class IdeHealthMonitor {
-  /**
-   * Create a new health monitor
-   * @param {Object} options
-   * @param {number} [options.cacheTtlMs=300000] - Cache TTL in milliseconds (default 5 minutes)
-   * @param {number} [options.maxFailures=3] - Failures before circuit opens
-   * @param {number} [options.circuitResetMs=600000] - Time before circuit resets (default 10 minutes)
-   */
-  constructor(options = {}) {
-    this.cacheTtlMs = options.cacheTtlMs || 300000; // 5 minutes default
-    this.maxFailures = options.maxFailures || 3;
-    this.circuitResetMs = options.circuitResetMs || 600000; // 10 minutes default
-
-    // Detection cache: { ideName: { result: boolean, cachedAt: timestamp, expiresAt: timestamp } }
-    this.detectionCache = new Map();
-
-    // Circuit breaker state: { ideName: { failures: number, openedAt: timestamp | null } }
-    this.circuitBreakers = new Map();
-
-    // Health metrics
-    this.metrics = {
-      totalChecks: 0,
-      cacheHits: 0,
-      cacheMisses: 0,
-      failures: 0,
-      circuitOpens: 0,
-      lastUpdated: null,
-    };
-  }
-
-  /**
-   * Check if an IDE is detected with caching
-   * @param {string} ideName - IDE identifier
-   * @param {string} projectDir - Project directory
-   * @param {Function} detectFn - Async function to perform actual detection
-   * @returns {Promise<{ detected: boolean, cached: boolean, circuitOpen: boolean }>}
-   */
-  async checkIde(ideName, projectDir, detectFn) {
-    this.metrics.totalChecks++;
-    const cacheKey = `${ideName}:${projectDir}`;
-
-    // Check circuit breaker first
-    const circuit = this.circuitBreakers.get(ideName);
-    if (circuit && circuit.openedAt) {
-      // Circuit is open - check if it should reset
-      if (Date.now() - circuit.openedAt > this.circuitResetMs) {
-        // Reset the circuit - allow half-open state
-        circuit.failures = 0;
-        circuit.openedAt = null;
-      } else {
-        // Circuit still open - return cached result or false
-        const cached = this.detectionCache.get(cacheKey);
-        return {
-          detected: cached ? cached.result : false,
-          cached: true,
-          circuitOpen: true,
-        };
-      }
-    }
-
-    // Check cache
-    const cachedEntry = this.detectionCache.get(cacheKey);
-    if (cachedEntry && Date.now() < cachedEntry.expiresAt) {
-      this.metrics.cacheHits++;
-      return {
-        detected: cachedEntry.result,
-        cached: true,
-        circuitOpen: false,
-      };
-    }
-
-    // Cache miss - perform actual detection
-    this.metrics.cacheMisses++;
-
-    try {
-      const startTime = Date.now();
-      const detected = await detectFn();
-      const duration = Date.now() - startTime;
-
-      // Cache the result
-      this.detectionCache.set(cacheKey, {
-        result: detected,
-        cachedAt: Date.now(),
-        expiresAt: Date.now() + this.cacheTtlMs,
-        duration,
-      });
-
-      // Reset failure count on success
-      if (this.circuitBreakers.has(ideName)) {
-        this.circuitBreakers.get(ideName).failures = 0;
-      }
-
-      return {
-        detected,
-        cached: false,
-        circuitOpen: false,
-        duration,
-      };
-    } catch (error) {
-      this.metrics.failures++;
-      this.recordFailure(ideName, error);
-
-      // Return cached value if available, otherwise false
-      const cached = this.detectionCache.get(cacheKey);
-      return {
-        detected: cached ? cached.result : false,
-        cached: !!cached,
-        circuitOpen: false,
-        error: error.message,
-      };
-    }
-  }
-
-  /**
-   * Record a detection failure for circuit breaker
-   * @param {string} ideName - IDE identifier
-   * @param {Error} error - The error that occurred
-   */
-  recordFailure(ideName, error) {
-    let circuit = this.circuitBreakers.get(ideName);
-    if (!circuit) {
-      circuit = { failures: 0, openedAt: null, lastError: null };
-      this.circuitBreakers.set(ideName, circuit);
-    }
-
-    circuit.failures++;
-    circuit.lastError = error.message;
-
-    // Check if we should open the circuit
-    if (circuit.failures >= this.maxFailures && !circuit.openedAt) {
-      circuit.openedAt = Date.now();
-      this.metrics.circuitOpens++;
-    }
-  }
-
-  /**
-   * Get circuit state for an IDE
-   * @param {string} ideName - IDE identifier
-   * @returns {{ open: boolean, failures: number, lastError: string | null }}
-   */
-  getCircuitState(ideName) {
-    const circuit = this.circuitBreakers.get(ideName);
-    if (!circuit) {
-      return { open: false, failures: 0, lastError: null };
-    }
-
-    // Check if circuit should auto-reset
-    if (circuit.openedAt && Date.now() - circuit.openedAt > this.circuitResetMs) {
-      return { open: false, failures: 0, lastError: circuit.lastError };
-    }
-
-    return {
-      open: !!circuit.openedAt,
-      failures: circuit.failures,
-      lastError: circuit.lastError,
-    };
-  }
-
-  /**
-   * Invalidate cache for a specific IDE/project
-   * @param {string} ideName - IDE identifier (or '*' for all)
-   * @param {string} [projectDir] - Project directory (optional)
-   */
-  invalidate(ideName, projectDir) {
-    if (ideName === '*') {
-      this.detectionCache.clear();
-      return;
-    }
-
-    if (projectDir) {
-      const cacheKey = `${ideName}:${projectDir}`;
-      this.detectionCache.delete(cacheKey);
-    } else {
-      // Remove all entries for this IDE
-      for (const key of this.detectionCache.keys()) {
-        if (key.startsWith(`${ideName}:`)) {
-          this.detectionCache.delete(key);
-        }
-      }
-    }
-  }
-
-  /**
-   * Get current health metrics
-   * @returns {Object} Health metrics
-   */
-  getMetrics() {
-    const hitRate =
-      this.metrics.cacheHits + this.metrics.cacheMisses > 0
-        ? (
-            (this.metrics.cacheHits / (this.metrics.cacheHits + this.metrics.cacheMisses)) *
-            100
-          ).toFixed(1) + '%'
-        : '0%';
-
-    return {
-      ...this.metrics,
-      cacheSize: this.detectionCache.size,
-      openCircuits: [...this.circuitBreakers.values()].filter(c => c.openedAt).length,
-      hitRate,
-      lastUpdated: new Date().toISOString(),
-    };
-  }
-
-  /**
-   * Save health metrics to file
-   * @param {string} projectDir - Project directory
-   * @returns {Promise<void>}
-   */
-  async saveMetrics(projectDir) {
-    const cacheDir = path.join(projectDir, '.agileflow', 'cache');
-    const metricsPath = path.join(cacheDir, 'ide-health.json');
-
-    try {
-      await fs.ensureDir(cacheDir);
-
-      const data = {
-        metrics: this.getMetrics(),
-        cache: this.getCacheSnapshot(),
-        circuits: this.getCircuitSnapshot(),
-        savedAt: new Date().toISOString(),
-      };
-
-      await fs.writeJson(metricsPath, data, { spaces: 2 });
-      this.metrics.lastUpdated = data.savedAt;
-    } catch {
-      // Silently ignore save errors - metrics are not critical
-    }
-  }
-
-  /**
-   * Load health metrics from file
-   * @param {string} projectDir - Project directory
-   * @returns {Promise<boolean>} True if loaded successfully
-   */
-  async loadMetrics(projectDir) {
-    const metricsPath = path.join(projectDir, '.agileflow', 'cache', 'ide-health.json');
-
-    try {
-      if (await fs.pathExists(metricsPath)) {
-        const data = await fs.readJson(metricsPath);
-
-        // Restore metrics (additive)
-        if (data.metrics) {
-          this.metrics.totalChecks += data.metrics.totalChecks || 0;
-          this.metrics.cacheHits += data.metrics.cacheHits || 0;
-          this.metrics.cacheMisses += data.metrics.cacheMisses || 0;
-          this.metrics.failures += data.metrics.failures || 0;
-          this.metrics.circuitOpens += data.metrics.circuitOpens || 0;
-        }
-
-        // Restore cache entries that haven't expired
-        if (data.cache) {
-          for (const [key, entry] of Object.entries(data.cache)) {
-            if (entry.expiresAt > Date.now()) {
-              this.detectionCache.set(key, entry);
-            }
-          }
-        }
-
-        // Restore circuit breaker state
-        if (data.circuits) {
-          for (const [key, state] of Object.entries(data.circuits)) {
-            this.circuitBreakers.set(key, state);
-          }
-        }
-
-        return true;
-      }
-    } catch {
-      // Ignore load errors
-    }
-    return false;
-  }
-
-  /**
-   * Get cache snapshot for persistence
-   * @returns {Object}
-   */
-  getCacheSnapshot() {
-    const snapshot = {};
-    for (const [key, entry] of this.detectionCache) {
-      snapshot[key] = entry;
-    }
-    return snapshot;
-  }
-
-  /**
-   * Get circuit breaker snapshot for persistence
-   * @returns {Object}
-   */
-  getCircuitSnapshot() {
-    const snapshot = {};
-    for (const [key, state] of this.circuitBreakers) {
-      snapshot[key] = state;
-    }
-    return snapshot;
-  }
-
-  /**
-   * Reset all state (for testing)
-   */
-  reset() {
-    this.detectionCache.clear();
-    this.circuitBreakers.clear();
-    this.metrics = {
-      totalChecks: 0,
-      cacheHits: 0,
-      cacheMisses: 0,
-      failures: 0,
-      circuitOpens: 0,
-      lastUpdated: null,
-    };
-  }
-}
-
-// Singleton instance for global usage
-let globalMonitor = null;
-
-/**
- * Get the global health monitor instance
- * @param {Object} [options] - Options for new instance
- * @returns {IdeHealthMonitor}
- */
-function getHealthMonitor(options) {
-  if (!globalMonitor) {
-    globalMonitor = new IdeHealthMonitor(options);
-  }
-  return globalMonitor;
-}
-
-/**
- * Reset the global monitor (for testing)
- */
-function resetHealthMonitor() {
-  if (globalMonitor) {
-    globalMonitor.reset();
-  }
-  globalMonitor = null;
-}
-
-module.exports = {
-  IdeHealthMonitor,
-  getHealthMonitor,
-  resetHealthMonitor,
-};