agileflow 2.89.3 → 2.90.0

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

@@ -0,0 +1,394 @@
+/**
+ * AgileFlow CLI - Configuration Manager
+ *
+ * Centralized configuration management with schema validation,
+ * migration support, and consistent access patterns.
+ *
+ * Usage:
+ *   const { ConfigManager } = require('./lib/config-manager');
+ *   const config = await ConfigManager.load(projectDir);
+ *   const userName = config.get('userName');
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+const { safeLoad, safeDump } = require('../../../lib/yaml-utils');
+
+/**
+ * Configuration schema definition
+ * @typedef {Object} ConfigSchema
+ * @property {string} type - Value type (string, array, boolean, number)
+ * @property {*} default - Default value
+ * @property {boolean} required - Whether the field is required
+ * @property {Function} [validate] - Custom validation function
+ */
+
+/**
+ * Configuration schema for AgileFlow manifest
+ */
+const CONFIG_SCHEMA = {
+  version: {
+    type: 'string',
+    default: '0.0.0',
+    required: true,
+    validate: v => /^\d+\.\d+\.\d+/.test(v),
+  },
+  userName: {
+    type: 'string',
+    default: 'Developer',
+    required: false,
+  },
+  ides: {
+    type: 'array',
+    default: ['claude-code'],
+    required: true,
+    validate: arr =>
+      Array.isArray(arr) &&
+      arr.every(ide => ['claude-code', 'cursor', 'windsurf', 'codex'].includes(ide)),
+  },
+  agileflowFolder: {
+    type: 'string',
+    default: '.agileflow',
+    required: true,
+    validate: v => typeof v === 'string' && v.length > 0 && !v.includes('..'),
+  },
+  docsFolder: {
+    type: 'string',
+    default: 'docs',
+    required: true,
+    validate: v => typeof v === 'string' && v.length > 0 && !v.includes('..'),
+  },
+  installedAt: {
+    type: 'string',
+    default: null,
+    required: false,
+  },
+  updatedAt: {
+    type: 'string',
+    default: null,
+    required: false,
+  },
+};
+
+/**
+ * Valid configuration keys (for external reference)
+ */
+const VALID_CONFIG_KEYS = Object.keys(CONFIG_SCHEMA);
+
+/**
+ * User-editable configuration keys
+ */
+const EDITABLE_CONFIG_KEYS = ['userName', 'ides', 'agileflowFolder', 'docsFolder'];
+
+/**
+ * Configuration Manager class
+ */
+class ConfigManager {
+  /**
+   * Create a new ConfigManager instance
+   * @param {Object} data - Configuration data
+   * @param {string} manifestPath - Path to manifest file
+   */
+  constructor(data = {}, manifestPath = null) {
+    this._data = { ...data };
+    this._manifestPath = manifestPath;
+    this._dirty = false;
+  }
+
+  /**
+   * Load configuration from a project directory
+   * @param {string} projectDir - Project directory
+   * @param {Object} options - Load options
+   * @param {string} [options.agileflowFolder='.agileflow'] - AgileFlow folder name
+   * @returns {Promise<ConfigManager>} ConfigManager instance
+   */
+  static async load(projectDir, options = {}) {
+    const agileflowFolder = options.agileflowFolder || '.agileflow';
+    const manifestPath = path.join(projectDir, agileflowFolder, '_cfg', 'manifest.yaml');
+
+    let data = {};
+
+    if (await fs.pathExists(manifestPath)) {
+      try {
+        const content = await fs.readFile(manifestPath, 'utf8');
+        const parsed = safeLoad(content);
+        // Normalize keys from snake_case to camelCase
+        data = ConfigManager._normalizeKeys(parsed);
+      } catch {
+        // If manifest is corrupted, use defaults
+        data = {};
+      }
+    }
+
+    // Apply defaults for missing fields
+    for (const [key, schema] of Object.entries(CONFIG_SCHEMA)) {
+      if (data[key] === undefined && schema.default !== null) {
+        data[key] = schema.default;
+      }
+    }
+
+    return new ConfigManager(data, manifestPath);
+  }
+
+  /**
+   * Normalize keys from snake_case to camelCase
+   * @param {Object} obj - Object with snake_case keys
+   * @returns {Object} Object with camelCase keys
+   */
+  static _normalizeKeys(obj) {
+    const keyMap = {
+      user_name: 'userName',
+      agileflow_folder: 'agileflowFolder',
+      docs_folder: 'docsFolder',
+      installed_at: 'installedAt',
+      updated_at: 'updatedAt',
+    };
+
+    const result = {};
+    for (const [key, value] of Object.entries(obj || {})) {
+      const normalizedKey = keyMap[key] || key;
+      result[normalizedKey] = value;
+    }
+    return result;
+  }
+
+  /**
+   * Denormalize keys from camelCase to snake_case for storage
+   * @param {Object} obj - Object with camelCase keys
+   * @returns {Object} Object with snake_case keys
+   */
+  static _denormalizeKeys(obj) {
+    const keyMap = {
+      userName: 'user_name',
+      agileflowFolder: 'agileflow_folder',
+      docsFolder: 'docs_folder',
+      installedAt: 'installed_at',
+      updatedAt: 'updated_at',
+    };
+
+    const result = {};
+    for (const [key, value] of Object.entries(obj || {})) {
+      const denormalizedKey = keyMap[key] || key;
+      result[denormalizedKey] = value;
+    }
+    return result;
+  }
+
+  /**
+   * Get a configuration value
+   * @param {string} key - Configuration key
+   * @returns {*} Configuration value
+   */
+  get(key) {
+    const schema = CONFIG_SCHEMA[key];
+    if (!schema) {
+      return undefined;
+    }
+    return this._data[key] !== undefined ? this._data[key] : schema.default;
+  }
+
+  /**
+   * Set a configuration value
+   * @param {string} key - Configuration key
+   * @param {*} value - Configuration value
+   * @returns {{ok: boolean, error?: string}} Result
+   */
+  set(key, value) {
+    const schema = CONFIG_SCHEMA[key];
+
+    if (!schema) {
+      return { ok: false, error: `Unknown configuration key: ${key}` };
+    }
+
+    if (!EDITABLE_CONFIG_KEYS.includes(key)) {
+      return { ok: false, error: `Configuration key '${key}' is read-only` };
+    }
+
+    // Type validation
+    const typeError = this._validateType(key, value, schema);
+    if (typeError) {
+      return { ok: false, error: typeError };
+    }
+
+    // Custom validation
+    if (schema.validate && !schema.validate(value)) {
+      return { ok: false, error: `Invalid value for '${key}'` };
+    }
+
+    this._data[key] = value;
+    this._dirty = true;
+    return { ok: true };
+  }
+
+  /**
+   * Validate type of a value
+   * @param {string} key - Configuration key
+   * @param {*} value - Value to validate
+   * @param {ConfigSchema} schema - Schema definition
+   * @returns {string|null} Error message or null if valid
+   */
+  _validateType(key, value, schema) {
+    switch (schema.type) {
+      case 'string':
+        if (typeof value !== 'string') {
+          return `'${key}' must be a string`;
+        }
+        break;
+      case 'array':
+        if (!Array.isArray(value)) {
+          return `'${key}' must be an array`;
+        }
+        break;
+      case 'boolean':
+        if (typeof value !== 'boolean') {
+          return `'${key}' must be a boolean`;
+        }
+        break;
+      case 'number':
+        if (typeof value !== 'number') {
+          return `'${key}' must be a number`;
+        }
+        break;
+    }
+    return null;
+  }
+
+  /**
+   * Validate all configuration values
+   * @returns {{ok: boolean, errors: string[]}} Validation result
+   */
+  validate() {
+    const errors = [];
+
+    for (const [key, schema] of Object.entries(CONFIG_SCHEMA)) {
+      const value = this._data[key];
+
+      // Check required fields
+      if (schema.required && (value === undefined || value === null)) {
+        errors.push(`Missing required field: ${key}`);
+        continue;
+      }
+
+      // Skip validation for undefined optional fields
+      if (value === undefined || value === null) {
+        continue;
+      }
+
+      // Type validation
+      const typeError = this._validateType(key, value, schema);
+      if (typeError) {
+        errors.push(typeError);
+        continue;
+      }
+
+      // Custom validation
+      if (schema.validate && !schema.validate(value)) {
+        errors.push(`Invalid value for '${key}'`);
+      }
+    }
+
+    return { ok: errors.length === 0, errors };
+  }
+
+  /**
+   * Save configuration to manifest file
+   * @returns {Promise<{ok: boolean, error?: string}>} Save result
+   */
+  async save() {
+    if (!this._manifestPath) {
+      return { ok: false, error: 'No manifest path set' };
+    }
+
+    try {
+      // Update timestamp
+      this._data.updatedAt = new Date().toISOString();
+
+      // Ensure directory exists
+      await fs.ensureDir(path.dirname(this._manifestPath));
+
+      // Denormalize keys for storage
+      const storageData = ConfigManager._denormalizeKeys(this._data);
+
+      // Write to file
+      await fs.writeFile(this._manifestPath, safeDump(storageData), 'utf8');
+
+      this._dirty = false;
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+  }
+
+  /**
+   * Get all configuration data
+   * @returns {Object} All configuration data
+   */
+  getAll() {
+    const result = {};
+    for (const key of VALID_CONFIG_KEYS) {
+      result[key] = this.get(key);
+    }
+    return result;
+  }
+
+  /**
+   * Check if configuration has unsaved changes
+   * @returns {boolean}
+   */
+  isDirty() {
+    return this._dirty;
+  }
+
+  /**
+   * Get the manifest file path
+   * @returns {string|null}
+   */
+  getManifestPath() {
+    return this._manifestPath;
+  }
+
+  /**
+   * Migrate configuration from an older format
+   * @param {Object} oldData - Old configuration data
+   * @returns {{ok: boolean, migrated: string[]}} Migration result
+   */
+  migrate(oldData) {
+    const migrated = [];
+
+    // Migration: rename 'name' to 'userName'
+    if (oldData.name && !this._data.userName) {
+      this._data.userName = oldData.name;
+      migrated.push('name → userName');
+      this._dirty = true;
+    }
+
+    // Migration: normalize IDE names
+    if (this._data.ides) {
+      const normalizedIdes = this._data.ides.map(ide => ide.toLowerCase());
+      if (JSON.stringify(normalizedIdes) !== JSON.stringify(this._data.ides)) {
+        this._data.ides = normalizedIdes;
+        migrated.push('ides normalized to lowercase');
+        this._dirty = true;
+      }
+    }
+
+    // Migration: ensure agileflowFolder starts with dot
+    if (
+      this._data.agileflowFolder &&
+      !this._data.agileflowFolder.startsWith('.') &&
+      this._data.agileflowFolder !== 'agileflow'
+    ) {
+      // Only migrate if it looks like it should have a dot
+      // Don't migrate 'agileflow' to '.agileflow' automatically
+    }
+
+    return { ok: true, migrated };
+  }
+}
+
+module.exports = {
+  ConfigManager,
+  CONFIG_SCHEMA,
+  VALID_CONFIG_KEYS,
+  EDITABLE_CONFIG_KEYS,
+};

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);
     });