agileflow 2.91.0 → 2.92.1

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

@@ -0,0 +1,364 @@
+/**
+ * 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,
+};

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

@@ -4,10 +4,13 @@
  * Centralized registry of supported IDEs with their metadata.
  * This eliminates duplicate IDE configuration scattered across commands.
  *
+ * Enhanced as part of US-0178: Consolidate IDE installer config into unified registry pattern
+ *
  * Usage:
  *   const { IdeRegistry } = require('./lib/ide-registry');
  *   const configPath = IdeRegistry.getConfigPath('claude-code', projectDir);
  *   const displayName = IdeRegistry.getDisplayName('cursor');
+ *   const config = IdeRegistry.get('windsurf');
  */
 
 const path = require('path');
@@ -18,9 +21,14 @@ const path = require('path');
  * @property {string} name - Internal IDE name (e.g., 'claude-code')
  * @property {string} displayName - Human-readable name (e.g., 'Claude Code')
  * @property {string} configDir - Base config directory (e.g., '.claude')
- * @property {string} targetSubdir - Target subdirectory for commands (e.g., 'commands/agileflow')
+ * @property {string} commandsSubdir - Subdirectory for commands (e.g., 'commands', 'workflows')
+ * @property {string} agileflowFolder - AgileFlow folder name (e.g., 'agileflow', 'AgileFlow')
+ * @property {string} targetSubdir - Full target path (computed from commandsSubdir + agileflowFolder)
  * @property {boolean} preferred - Whether this is a preferred IDE
+ * @property {string} description - Short description for UI
  * @property {string} [handler] - Handler class name (e.g., 'ClaudeCodeSetup')
+ * @property {Object} labels - Custom labels for installed content
+ * @property {Object} features - Feature flags for this IDE
  */
 
 /**
@@ -32,33 +40,83 @@ const IDE_REGISTRY = {
     name: 'claude-code',
     displayName: 'Claude Code',
     configDir: '.claude',
+    commandsSubdir: 'commands',
+    agileflowFolder: 'agileflow',
     targetSubdir: 'commands/agileflow', // lowercase
     preferred: true,
+    description: "Anthropic's Claude Code IDE",
     handler: 'ClaudeCodeSetup',
+    labels: {
+      commands: 'commands',
+      agents: 'agents',
+    },
+    features: {
+      spawnableAgents: true, // Has .claude/agents/ for Task tool
+      skills: true, // Has .claude/skills/ for user skills
+      damageControl: true, // Supports PreToolUse hooks
+    },
   },
   cursor: {
     name: 'cursor',
     displayName: 'Cursor',
     configDir: '.cursor',
+    commandsSubdir: 'commands',
+    agileflowFolder: 'AgileFlow',
     targetSubdir: 'commands/AgileFlow', // PascalCase
     preferred: false,
+    description: 'AI-powered code editor',
     handler: 'CursorSetup',
+    labels: {
+      commands: 'commands',
+      agents: 'agents',
+    },
+    features: {
+      spawnableAgents: false,
+      skills: false,
+      damageControl: false,
+    },
   },
   windsurf: {
     name: 'windsurf',
     displayName: 'Windsurf',
     configDir: '.windsurf',
+    commandsSubdir: 'workflows',
+    agileflowFolder: 'agileflow',
     targetSubdir: 'workflows/agileflow', // lowercase
-    preferred: true,
+    preferred: false,
+    description: "Codeium's AI IDE",
     handler: 'WindsurfSetup',
+    labels: {
+      commands: 'workflows',
+      agents: 'agent workflows',
+    },
+    features: {
+      spawnableAgents: false,
+      skills: false,
+      damageControl: false,
+    },
   },
   codex: {
     name: 'codex',
     displayName: 'OpenAI Codex CLI',
     configDir: '.codex',
+    commandsSubdir: 'skills',
+    agileflowFolder: 'agileflow',
     targetSubdir: 'skills', // Codex uses skills directory
     preferred: false,
+    description: "OpenAI's Codex CLI",
     handler: 'CodexSetup',
+    labels: {
+      commands: 'prompts',
+      agents: 'skills',
+    },
+    features: {
+      spawnableAgents: false,
+      skills: true, // Has .codex/skills/
+      damageControl: false,
+      customInstall: true, // Uses custom install flow (not setupStandard)
+      agentsMd: true, // Creates AGENTS.md at project root
+    },
   },
 };
 
@@ -178,6 +236,59 @@ class IdeRegistry {
     const ide = IDE_REGISTRY[ideName];
     return ide ? ide.handler : null;
   }
+
+  /**
+   * Get IDE choices formatted for UI selection (inquirer checkbox format)
+   * @returns {Array} Array of {name, value, checked, configDir, description}
+   */
+  static getChoices() {
+    return Object.values(IDE_REGISTRY)
+      .sort((a, b) => {
+        // Preferred first, then alphabetical
+        if (a.preferred && !b.preferred) return -1;
+        if (!a.preferred && b.preferred) return 1;
+        return a.displayName.localeCompare(b.displayName);
+      })
+      .map((ide, index) => ({
+        name: ide.displayName,
+        value: ide.name,
+        checked: ide.preferred || index === 0,
+        configDir: `${ide.configDir}/${ide.commandsSubdir}`,
+        description: ide.description,
+      }));
+  }
+
+  /**
+   * Check if an IDE has a specific feature
+   * @param {string} ideName - IDE name
+   * @param {string} featureName - Feature to check
+   * @returns {boolean}
+   */
+  static hasFeature(ideName, featureName) {
+    const ide = IDE_REGISTRY[ideName];
+    return !!(ide && ide.features && ide.features[featureName]);
+  }
+
+  /**
+   * Get all IDEs with a specific feature
+   * @param {string} featureName - Feature to filter by
+   * @returns {string[]} Array of IDE names
+   */
+  static getWithFeature(featureName) {
+    return Object.entries(IDE_REGISTRY)
+      .filter(([, meta]) => meta.features && meta.features[featureName])
+      .map(([name]) => name);
+  }
+
+  /**
+   * Get labels for an IDE (e.g., 'commands' vs 'workflows')
+   * @param {string} ideName - IDE name
+   * @returns {Object} Labels object {commands, agents}
+   */
+  static getLabels(ideName) {
+    const ide = IDE_REGISTRY[ideName];
+    return ide && ide.labels ? ide.labels : { commands: 'commands', agents: 'agents' };
+  }
 }
 
 module.exports = {

package/tools/cli/lib/ui.js

@@ -9,6 +9,7 @@ const inquirer = require('inquirer');
 const path = require('node:path');
 const fs = require('node:fs');
 const { IdeManager } = require('../installers/ide/manager');
+const { IdeRegistry } = require('./ide-registry');
 const { BRAND_HEX } = require('../../../lib/colors');
 
 // Load package.json for version
@@ -95,31 +96,10 @@ function getIdeChoices() {
 
 /**
  * @deprecated Use getIdeChoices() instead - dynamically loaded from IDE handlers
- * Legacy hardcoded IDE choices kept for backward compatibility
+ * Legacy hardcoded IDE choices - now sourced from IdeRegistry for consistency
+ * Kept for backward compatibility with code that imports IDE_CHOICES directly
  */
-const IDE_CHOICES = [
-  {
-    name: 'Claude Code',
-    value: 'claude-code',
-    checked: true,
-    configDir: '.claude/commands',
-    description: "Anthropic's Claude Code IDE",
-  },
-  {
-    name: 'Cursor',
-    value: 'cursor',
-    checked: false,
-    configDir: '.cursor/rules',
-    description: 'AI-powered code editor',
-  },
-  {
-    name: 'Windsurf',
-    value: 'windsurf',
-    checked: false,
-    configDir: '.windsurf/workflows',
-    description: "Codeium's AI IDE",
-  },
-];
+const IDE_CHOICES = IdeRegistry.getChoices();
 
 /**
  * Prompt for installation configuration
@@ -191,6 +171,13 @@ async function promptInstall() {
       message: 'Create/update .gitignore with recommended entries?',
       default: true,
     },
+    {
+      type: 'confirm',
+      name: 'claudeMdReinforcement',
+      message:
+        'Add /babysit AskUserQuestion rules to CLAUDE.md? (recommended for context preservation)',
+      default: true,
+    },
   ]);
 
   return {
@@ -200,6 +187,7 @@ async function promptInstall() {
     agileflowFolder: answers.agileflowFolder,
     docsFolder: answers.docsFolder,
     updateGitignore: answers.updateGitignore,
+    claudeMdReinforcement: answers.claudeMdReinforcement,
   };
 }
 
@@ -223,11 +211,13 @@ async function confirm(message, defaultValue = true) {
 
 /**
  * Get IDE configuration by name
+ * Uses IdeRegistry for consistent configuration
  * @param {string} ideName - IDE name
  * @returns {Object|null}
  */
 function getIdeConfig(ideName) {
-  return IDE_CHOICES.find(ide => ide.value === ideName) || null;
+  // Use IdeRegistry as the single source of truth
+  return IdeRegistry.get(ideName);
 }
 
 module.exports = {