agileflow 2.89.2 → 2.90.0

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

@@ -4,8 +4,15 @@
  * Provides specific error types for common IDE setup failures.
  * These errors carry context about what failed and why,
  * enabling better error handling and user feedback.
+ *
+ * Integration with error-codes.js:
+ * - All IDE errors now have errorCode, severity, category metadata
+ * - Use formatError() from error-codes.js for consistent display
+ * - isRecoverable() works with these errors
  */
 
+const { ErrorCodes, Severity, Category } = require('../../../lib/error-codes');
+
 /**
  * Base error class for IDE-related errors.
  * All IDE errors extend this class.
@@ -15,13 +22,22 @@ class IdeError extends Error {
    * @param {string} message - Error description
    * @param {string} ideName - Name of the IDE (e.g., 'Claude Code', 'Cursor')
    * @param {Object} [context={}] - Additional context about the error
+   * @param {string} [errorCode='EUNKNOWN'] - Error code from error-codes.js
    */
-  constructor(message, ideName, context = {}) {
+  constructor(message, ideName, context = {}, errorCode = 'EUNKNOWN') {
     super(message);
     this.name = this.constructor.name;
     this.ideName = ideName;
     this.context = context;
     Error.captureStackTrace(this, this.constructor);
+
+    // Attach error code metadata from unified error codes
+    const codeData = ErrorCodes[errorCode] || ErrorCodes.EUNKNOWN;
+    this.errorCode = codeData.code;
+    this.severity = codeData.severity;
+    this.category = codeData.category;
+    this.recoverable = codeData.recoverable;
+    this.autoFix = codeData.autoFix || null;
   }
 
   /**
@@ -31,6 +47,16 @@ class IdeError extends Error {
   getUserMessage() {
     return `${this.ideName}: ${this.message}`;
   }
+
+  /**
+   * Get suggested action to fix the error
+   * Override in subclasses for specific suggestions
+   * @returns {string}
+   */
+  getSuggestedAction() {
+    const codeData = ErrorCodes[this.errorCode] || ErrorCodes.EUNKNOWN;
+    return codeData.suggestedFix;
+  }
 }
 
 /**
@@ -44,10 +70,12 @@ class IdeConfigNotFoundError extends IdeError {
    * @param {Object} [context={}] - Additional context
    */
   constructor(ideName, configPath, context = {}) {
-    super(`Configuration directory not found: ${configPath}`, ideName, {
-      configPath,
-      ...context,
-    });
+    super(
+      `Configuration directory not found: ${configPath}`,
+      ideName,
+      { configPath, ...context },
+      'ENODIR' // Use unified error code
+    );
     this.configPath = configPath;
   }
 
@@ -72,11 +100,23 @@ class CommandInstallationError extends IdeError {
    * @param {Object} [context={}] - Additional context
    */
   constructor(ideName, commandName, reason, context = {}) {
-    super(`Failed to install command '${commandName}': ${reason}`, ideName, {
-      commandName,
-      reason,
-      ...context,
-    });
+    // Detect appropriate error code from reason
+    let errorCode = 'ESTATE';
+    if (reason.toLowerCase().includes('permission')) {
+      errorCode = 'EACCES';
+    } else if (
+      reason.toLowerCase().includes('not found') ||
+      reason.toLowerCase().includes('no such')
+    ) {
+      errorCode = 'ENOENT';
+    }
+
+    super(
+      `Failed to install command '${commandName}': ${reason}`,
+      ideName,
+      { commandName, reason, ...context },
+      errorCode
+    );
     this.commandName = commandName;
     this.reason = reason;
   }
@@ -108,11 +148,12 @@ class FilePermissionError extends IdeError {
    * @param {Object} [context={}] - Additional context
    */
   constructor(ideName, filePath, operation, context = {}) {
-    super(`Permission denied: cannot ${operation} '${filePath}'`, ideName, {
-      filePath,
-      operation,
-      ...context,
-    });
+    super(
+      `Permission denied: cannot ${operation} '${filePath}'`,
+      ideName,
+      { filePath, operation, ...context },
+      'EACCES' // Use unified error code
+    );
     this.filePath = filePath;
     this.operation = operation;
   }
@@ -138,14 +179,23 @@ class ContentInjectionError extends IdeError {
    * @param {Object} [context={}] - Additional context
    */
   constructor(ideName, templateFile, reason, context = {}) {
-    super(`Content injection failed for '${templateFile}': ${reason}`, ideName, {
-      templateFile,
-      reason,
-      ...context,
-    });
+    super(
+      `Content injection failed for '${templateFile}': ${reason}`,
+      ideName,
+      { templateFile, reason, ...context },
+      'ECONFIG' // Use unified error code - configuration/template issue
+    );
     this.templateFile = templateFile;
     this.reason = reason;
   }
+
+  /**
+   * Get suggested action to fix the error
+   * @returns {string}
+   */
+  getSuggestedAction() {
+    return `Check the template file '${this.templateFile}' for valid placeholders. Run "npx agileflow doctor --fix" to repair.`;
+  }
 }
 
 /**
@@ -160,14 +210,34 @@ class CleanupError extends IdeError {
    * @param {Object} [context={}] - Additional context
    */
   constructor(ideName, targetPath, reason, context = {}) {
-    super(`Cleanup failed for '${targetPath}': ${reason}`, ideName, {
-      targetPath,
-      reason,
-      ...context,
-    });
+    // Detect appropriate error code from reason
+    let errorCode = 'ESTATE';
+    if (reason.toLowerCase().includes('lock') || reason.toLowerCase().includes('busy')) {
+      errorCode = 'ELOCK';
+    } else if (reason.toLowerCase().includes('permission')) {
+      errorCode = 'EACCES';
+    }
+
+    super(
+      `Cleanup failed for '${targetPath}': ${reason}`,
+      ideName,
+      { targetPath, reason, ...context },
+      errorCode
+    );
     this.targetPath = targetPath;
     this.reason = reason;
   }
+
+  /**
+   * Get suggested action to fix the error
+   * @returns {string}
+   */
+  getSuggestedAction() {
+    if (this.errorCode === 'ELOCK') {
+      return `Close any applications using files in '${this.targetPath}' and try again.`;
+    }
+    return `Check permissions on '${this.targetPath}' or remove it manually.`;
+  }
 }
 
 /**
@@ -181,12 +251,29 @@ class IdeDetectionError extends IdeError {
    * @param {Object} [context={}] - Additional context
    */
   constructor(ideName, reason, context = {}) {
-    super(`IDE detection failed: ${reason}`, ideName, {
-      reason,
-      ...context,
-    });
+    // Detect appropriate error code
+    let errorCode = 'ECONFLICT';
+    if (
+      reason.toLowerCase().includes('not found') ||
+      reason.toLowerCase().includes('not installed')
+    ) {
+      errorCode = 'ENOENT';
+    }
+
+    super(`IDE detection failed: ${reason}`, ideName, { reason, ...context }, errorCode);
     this.reason = reason;
   }
+
+  /**
+   * Get suggested action to fix the error
+   * @returns {string}
+   */
+  getSuggestedAction() {
+    if (this.errorCode === 'ENOENT') {
+      return `Install ${this.ideName} and run it at least once to initialize configuration.`;
+    }
+    return `Check IDE configuration and resolve any conflicts. Run "npx agileflow doctor" for details.`;
+  }
 }
 
 /**
@@ -220,6 +307,52 @@ function isIdeError(error) {
   return error instanceof IdeError;
 }
 
+/**
+ * Format an IDE error for display using unified error code format
+ * @param {IdeError} error - IDE error to format
+ * @param {Object} [options={}] - Format options
+ * @param {boolean} [options.includeStack=false] - Include stack trace
+ * @param {boolean} [options.includeSuggestion=true] - Include suggested action
+ * @returns {string} Formatted error string
+ */
+function formatIdeError(error, options = {}) {
+  const { includeStack = false, includeSuggestion = true } = options;
+
+  if (!error) return 'Unknown error';
+
+  const lines = [];
+
+  // Main error line with IDE name and error code
+  lines.push(`[${error.errorCode}] ${error.ideName}: ${error.message}`);
+
+  // Severity and category
+  lines.push(`  Severity: ${error.severity} | Category: ${error.category}`);
+
+  // Suggested action (IDE-specific takes precedence)
+  if (includeSuggestion) {
+    const suggestion = error.getSuggestedAction?.() || error.suggestedFix;
+    if (suggestion) {
+      lines.push(`  Fix: ${suggestion}`);
+    }
+  }
+
+  // Recoverable status
+  lines.push(`  Recoverable: ${error.recoverable ? 'Yes' : 'No'}`);
+
+  // Auto-fix availability
+  if (error.autoFix) {
+    lines.push(`  Auto-fix available: npx agileflow doctor --fix`);
+  }
+
+  // Stack trace
+  if (includeStack && error.stack) {
+    lines.push('');
+    lines.push(error.stack);
+  }
+
+  return lines.join('\n');
+}
+
 module.exports = {
   IdeError,
   IdeConfigNotFoundError,
@@ -230,4 +363,5 @@ module.exports = {
   IdeDetectionError,
   withPermissionHandling,
   isIdeError,
+  formatIdeError,
 };

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

@@ -0,0 +1,186 @@
+/**
+ * AgileFlow CLI - IDE Registry
+ *
+ * Centralized registry of supported IDEs with their metadata.
+ * This eliminates duplicate IDE configuration scattered across commands.
+ *
+ * Usage:
+ *   const { IdeRegistry } = require('./lib/ide-registry');
+ *   const configPath = IdeRegistry.getConfigPath('claude-code', projectDir);
+ *   const displayName = IdeRegistry.getDisplayName('cursor');
+ */
+
+const path = require('path');
+
+/**
+ * IDE metadata definition
+ * @typedef {Object} IdeMetadata
+ * @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 {boolean} preferred - Whether this is a preferred IDE
+ * @property {string} [handler] - Handler class name (e.g., 'ClaudeCodeSetup')
+ */
+
+/**
+ * Registry of all supported IDEs
+ * @type {Object.<string, IdeMetadata>}
+ */
+const IDE_REGISTRY = {
+  'claude-code': {
+    name: 'claude-code',
+    displayName: 'Claude Code',
+    configDir: '.claude',
+    targetSubdir: 'commands/agileflow', // lowercase
+    preferred: true,
+    handler: 'ClaudeCodeSetup',
+  },
+  cursor: {
+    name: 'cursor',
+    displayName: 'Cursor',
+    configDir: '.cursor',
+    targetSubdir: 'commands/AgileFlow', // PascalCase
+    preferred: false,
+    handler: 'CursorSetup',
+  },
+  windsurf: {
+    name: 'windsurf',
+    displayName: 'Windsurf',
+    configDir: '.windsurf',
+    targetSubdir: 'workflows/agileflow', // lowercase
+    preferred: true,
+    handler: 'WindsurfSetup',
+  },
+  codex: {
+    name: 'codex',
+    displayName: 'OpenAI Codex CLI',
+    configDir: '.codex',
+    targetSubdir: 'skills', // Codex uses skills directory
+    preferred: false,
+    handler: 'CodexSetup',
+  },
+};
+
+/**
+ * IDE Registry class providing centralized IDE metadata access
+ */
+class IdeRegistry {
+  /**
+   * Get all registered IDE names
+   * @returns {string[]} List of IDE names
+   */
+  static getAll() {
+    return Object.keys(IDE_REGISTRY);
+  }
+
+  /**
+   * Get all IDE metadata
+   * @returns {Object.<string, IdeMetadata>} All IDE metadata
+   */
+  static getAllMetadata() {
+    return { ...IDE_REGISTRY };
+  }
+
+  /**
+   * Get metadata for a specific IDE
+   * @param {string} ideName - IDE name
+   * @returns {IdeMetadata|null} IDE metadata or null if not found
+   */
+  static get(ideName) {
+    return IDE_REGISTRY[ideName] || null;
+  }
+
+  /**
+   * Check if an IDE is registered
+   * @param {string} ideName - IDE name
+   * @returns {boolean}
+   */
+  static exists(ideName) {
+    return ideName in IDE_REGISTRY;
+  }
+
+  /**
+   * Get the config path for an IDE in a project
+   * @param {string} ideName - IDE name
+   * @param {string} projectDir - Project directory
+   * @returns {string} Full path to IDE config directory
+   */
+  static getConfigPath(ideName, projectDir) {
+    const ide = IDE_REGISTRY[ideName];
+    if (!ide) {
+      return '';
+    }
+    return path.join(projectDir, ide.configDir, ide.targetSubdir);
+  }
+
+  /**
+   * Get the base config directory for an IDE (e.g., .claude, .cursor)
+   * @param {string} ideName - IDE name
+   * @param {string} projectDir - Project directory
+   * @returns {string} Full path to base config directory
+   */
+  static getBaseDir(ideName, projectDir) {
+    const ide = IDE_REGISTRY[ideName];
+    if (!ide) {
+      return '';
+    }
+    return path.join(projectDir, ide.configDir);
+  }
+
+  /**
+   * Get the display name for an IDE
+   * @param {string} ideName - IDE name
+   * @returns {string} Display name or the original name if not found
+   */
+  static getDisplayName(ideName) {
+    const ide = IDE_REGISTRY[ideName];
+    return ide ? ide.displayName : ideName;
+  }
+
+  /**
+   * Get all preferred IDEs
+   * @returns {string[]} List of preferred IDE names
+   */
+  static getPreferred() {
+    return Object.entries(IDE_REGISTRY)
+      .filter(([, meta]) => meta.preferred)
+      .map(([name]) => name);
+  }
+
+  /**
+   * Validate IDE name
+   * @param {string} ideName - IDE name to validate
+   * @returns {{ok: boolean, error?: string}} Validation result
+   */
+  static validate(ideName) {
+    if (!ideName || typeof ideName !== 'string') {
+      return { ok: false, error: 'IDE name must be a non-empty string' };
+    }
+
+    if (!IDE_REGISTRY[ideName]) {
+      const validNames = Object.keys(IDE_REGISTRY).join(', ');
+      return {
+        ok: false,
+        error: `Unknown IDE: '${ideName}'. Valid options: ${validNames}`,
+      };
+    }
+
+    return { ok: true };
+  }
+
+  /**
+   * Get handler class name for an IDE
+   * @param {string} ideName - IDE name
+   * @returns {string|null} Handler class name or null
+   */
+  static getHandler(ideName) {
+    const ide = IDE_REGISTRY[ideName];
+    return ide ? ide.handler : null;
+  }
+}
+
+module.exports = {
+  IdeRegistry,
+  IDE_REGISTRY,
+};

package/tools/cli/lib/npm-utils.js

@@ -40,6 +40,9 @@ async function getLatestVersion(packageName) {
       headers: {
         'User-Agent': 'agileflow-cli',
       },
+      // Security: Explicitly enable TLS certificate validation
+      // Prevents MITM attacks on npm registry requests
+      rejectUnauthorized: true,
     };
 
     debugLog('Fetching version', { package: packageName, path: options.path });
@@ -70,12 +73,22 @@ async function getLatestVersion(packageName) {
     });
 
     req.on('error', err => {
-      debugLog('Network error', { error: err.message });
+      // Enhanced error logging with retry guidance
+      const errorInfo = {
+        error: err.message,
+        code: err.code,
+        suggestion: 'Check network connection. If error persists, try: npm cache clean --force',
+      };
+      if (err.code === 'CERT_HAS_EXPIRED' || err.code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') {
+        errorInfo.suggestion = 'TLS certificate error - check system time or update CA certificates';
+      }
+      debugLog('Network error', errorInfo);
       resolve(null);
     });
 
-    req.setTimeout(5000, () => {
-      debugLog('Request timeout');
+    // 10 second timeout for registry requests
+    req.setTimeout(10000, () => {
+      debugLog('Request timeout (10s)', { suggestion: 'npm registry may be slow. Retry later.' });
       req.destroy();
       resolve(null);
     });

package/tools/cli/lib/self-update.js

@@ -0,0 +1,148 @@
+/**
+ * AgileFlow CLI - Self-Update Module
+ *
+ * Provides self-update capability for the CLI to ensure users
+ * always run the latest version.
+ *
+ * Usage:
+ *   const { checkSelfUpdate, performSelfUpdate } = require('./lib/self-update');
+ *   await checkSelfUpdate(options, 'update');
+ */
+
+const path = require('path');
+const { spawnSync } = require('node:child_process');
+const semver = require('semver');
+const chalk = require('chalk');
+const { getLatestVersion } = require('./npm-utils');
+const { info } = require('./ui');
+
+/**
+ * Get the local CLI version from package.json
+ * @returns {string} Local CLI version
+ */
+function getLocalVersion() {
+  const packageJson = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+  return packageJson.version;
+}
+
+/**
+ * Check if a self-update is needed
+ * @param {Object} options - Command options
+ * @param {boolean} [options.selfUpdate=true] - Whether self-update is enabled
+ * @param {boolean} [options.selfUpdated=false] - Whether already self-updated
+ * @returns {Promise<{needed: boolean, localVersion: string, latestVersion: string|null}>}
+ */
+async function checkSelfUpdate(options = {}) {
+  const shouldCheck = options.selfUpdate !== false && !options.selfUpdated;
+
+  if (!shouldCheck) {
+    return {
+      needed: false,
+      localVersion: getLocalVersion(),
+      latestVersion: null,
+    };
+  }
+
+  const localVersion = getLocalVersion();
+  const latestVersion = await getLatestVersion('agileflow');
+
+  if (!latestVersion) {
+    return {
+      needed: false,
+      localVersion,
+      latestVersion: null,
+    };
+  }
+
+  const needed = semver.lt(localVersion, latestVersion);
+
+  return {
+    needed,
+    localVersion,
+    latestVersion,
+  };
+}
+
+/**
+ * Perform self-update by re-running with latest CLI version
+ * @param {string} command - Command name to re-run
+ * @param {Object} options - Command options
+ * @param {Object} versionInfo - Version info from checkSelfUpdate
+ * @returns {number} Exit code from spawned process
+ */
+function performSelfUpdate(command, options, versionInfo) {
+  const { localVersion, latestVersion } = versionInfo;
+
+  // Display update notice
+  console.log(chalk.hex('#e8683a').bold('\n  AgileFlow CLI Update\n'));
+  info(`Updating CLI from v${localVersion} to v${latestVersion}...`);
+  console.log(chalk.dim('  Fetching latest version from npm...\n'));
+
+  // Build the command with all current options forwarded
+  const args = ['agileflow@latest', command, '--self-updated'];
+
+  // Forward common options
+  if (options.directory) args.push('-d', options.directory);
+  if (options.force) args.push('--force');
+
+  // Forward command-specific options
+  if (command === 'update' && options.ides) {
+    args.push('--ides', options.ides);
+  }
+
+  const result = spawnSync('npx', args, {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    shell: process.platform === 'win32',
+  });
+
+  return result.status ?? 0;
+}
+
+/**
+ * Check and perform self-update if needed
+ * Returns true if the caller should exit (because update was performed)
+ * @param {string} command - Command name
+ * @param {Object} options - Command options
+ * @returns {Promise<boolean>} True if caller should exit
+ */
+async function handleSelfUpdate(command, options) {
+  const versionInfo = await checkSelfUpdate(options);
+
+  if (versionInfo.needed) {
+    const exitCode = performSelfUpdate(command, options, versionInfo);
+    process.exit(exitCode);
+    return true; // Never reached, but for type safety
+  }
+
+  return false;
+}
+
+/**
+ * Middleware for self-update check
+ * @param {string} command - Command name
+ * @returns {Function} Middleware function
+ */
+function selfUpdateMiddleware(command) {
+  return async (ctx, next) => {
+    const versionInfo = await checkSelfUpdate(ctx.options);
+
+    if (versionInfo.needed) {
+      const exitCode = performSelfUpdate(command, ctx.options, versionInfo);
+      process.exit(exitCode);
+      return; // Never reached
+    }
+
+    // Store version info in context for later use
+    ctx.versionInfo = versionInfo;
+    await next();
+  };
+}
+
+module.exports = {
+  getLocalVersion,
+  checkSelfUpdate,
+  performSelfUpdate,
+  handleSelfUpdate,
+  selfUpdateMiddleware,
+};