agileflow 2.89.2 → 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/content-injector.js

@@ -33,6 +33,13 @@ const {
   countSkills,
   getCounts,
 } = require('../../../scripts/lib/counter');
+const {
+  sanitize,
+  sanitizeAgentData,
+  sanitizeCommandData,
+  validatePlaceholderValue,
+  detectInjectionAttempt,
+} = require('../../../lib/content-sanitizer');
 
 // =============================================================================
 // List Generation Functions
@@ -41,12 +48,14 @@ const {
 /**
  * Validate that a file path is within the expected directory.
  * Prevents reading files outside the expected scope.
+ * Security: Symlinks are NOT allowed to prevent escape attacks.
  * @param {string} filePath - File path to validate
  * @param {string} baseDir - Expected base directory
  * @returns {boolean} True if path is safe
  */
 function isPathSafe(filePath, baseDir) {
-  const result = validatePath(filePath, baseDir, { allowSymlinks: true });
+  // Security hardening (US-0104): Symlinks disabled to prevent escape attacks
+  const result = validatePath(filePath, baseDir, { allowSymlinks: false });
   return result.ok;
 }
 
@@ -76,19 +85,32 @@ function generateAgentList(agentsDir) {
       continue;
     }
 
-    agents.push({
+    // Sanitize agent data to prevent injection attacks
+    const rawAgent = {
       name: frontmatter.name || path.basename(file, '.md'),
       description: frontmatter.description || '',
       tools: normalizeTools(frontmatter.tools),
       model: frontmatter.model || 'haiku',
-    });
+    };
+
+    const sanitizedAgent = sanitizeAgentData(rawAgent);
+
+    // Skip if sanitization produced invalid data
+    if (!sanitizedAgent.name || sanitizedAgent.name === 'unknown') {
+      continue;
+    }
+
+    agents.push(sanitizedAgent);
   }
 
   agents.sort((a, b) => a.name.localeCompare(b.name));
 
-  let output = `**AVAILABLE AGENTS (${agents.length} total)**:\n\n`;
+  // Sanitize the count value
+  const safeCount = sanitize.count(agents.length);
+  let output = `**AVAILABLE AGENTS (${safeCount} total)**:\n\n`;
 
   agents.forEach((agent, index) => {
+    // All values are already sanitized by sanitizeAgentData
     output += `${index + 1}. **${agent.name}** (model: ${agent.model})\n`;
     output += `   - **Purpose**: ${agent.description}\n`;
     output += `   - **Tools**: ${agent.tools.join(', ')}\n`;
@@ -127,11 +149,19 @@ function generateCommandList(commandsDir) {
       continue;
     }
 
-    commands.push({
+    // Sanitize command data to prevent injection attacks
+    const rawCommand = {
       name: cmdName,
       description: frontmatter.description || '',
       argumentHint: frontmatter['argument-hint'] || '',
-    });
+    };
+
+    const sanitizedCommand = sanitizeCommandData(rawCommand);
+    if (!sanitizedCommand.name || sanitizedCommand.name === 'unknown') {
+      continue;
+    }
+
+    commands.push(sanitizedCommand);
   }
 
   // Scan subdirectories (e.g., session/)
@@ -163,20 +193,31 @@ function generateCommandList(commandsDir) {
           continue;
         }
 
-        commands.push({
+        // Sanitize command data
+        const rawCommand = {
           name: cmdName,
           description: frontmatter.description || '',
           argumentHint: frontmatter['argument-hint'] || '',
-        });
+        };
+
+        const sanitizedCommand = sanitizeCommandData(rawCommand);
+        if (!sanitizedCommand.name || sanitizedCommand.name === 'unknown') {
+          continue;
+        }
+
+        commands.push(sanitizedCommand);
       }
     }
   }
 
   commands.sort((a, b) => a.name.localeCompare(b.name));
 
-  let output = `Available commands (${commands.length} total):\n`;
+  // Sanitize the count value
+  const safeCount = sanitize.count(commands.length);
+  let output = `Available commands (${safeCount} total):\n`;
 
   commands.forEach(cmd => {
+    // All values are already sanitized by sanitizeCommandData
     const argHint = cmd.argumentHint ? ` ${cmd.argumentHint}` : '';
     output += `- \`/agileflow:${cmd.name}${argHint}\` - ${cmd.description}\n`;
   });
@@ -208,16 +249,28 @@ function injectContent(content, context = {}) {
     counts = getCounts(coreDir);
   }
 
+  // Validate and sanitize all placeholder values before injection
+  const safeCommandCount = validatePlaceholderValue('COMMAND_COUNT', counts.commands).sanitized;
+  const safeAgentCount = validatePlaceholderValue('AGENT_COUNT', counts.agents).sanitized;
+  const safeSkillCount = validatePlaceholderValue('SKILL_COUNT', counts.skills).sanitized;
+  const safeVersion = validatePlaceholderValue('VERSION', version).sanitized;
+  const safeDate = validatePlaceholderValue('INSTALL_DATE', new Date()).sanitized;
+  const safeAgileflowFolder = validatePlaceholderValue(
+    'agileflow_folder',
+    agileflowFolder
+  ).sanitized;
+
   // Replace count placeholders (both formats: {{X}} and <!-- {{X}} -->)
-  result = result.replace(/\{\{COMMAND_COUNT\}\}/g, String(counts.commands));
-  result = result.replace(/\{\{AGENT_COUNT\}\}/g, String(counts.agents));
-  result = result.replace(/\{\{SKILL_COUNT\}\}/g, String(counts.skills));
+  result = result.replace(/\{\{COMMAND_COUNT\}\}/g, String(safeCommandCount));
+  result = result.replace(/\{\{AGENT_COUNT\}\}/g, String(safeAgentCount));
+  result = result.replace(/\{\{SKILL_COUNT\}\}/g, String(safeSkillCount));
 
   // Replace metadata placeholders
-  result = result.replace(/\{\{VERSION\}\}/g, version);
-  result = result.replace(/\{\{INSTALL_DATE\}\}/g, new Date().toISOString().split('T')[0]);
+  result = result.replace(/\{\{VERSION\}\}/g, safeVersion);
+  result = result.replace(/\{\{INSTALL_DATE\}\}/g, safeDate);
 
   // Replace list placeholders (only if core directory available)
+  // List generation already includes sanitization via sanitizeAgentData/sanitizeCommandData
   if (coreDir && fs.existsSync(coreDir)) {
     if (result.includes('{{AGENT_LIST}}')) {
       const agentList = generateAgentList(path.join(coreDir, 'agents'));
@@ -232,8 +285,8 @@ function injectContent(content, context = {}) {
     }
   }
 
-  // Replace folder placeholders
-  result = result.replace(/\{agileflow_folder\}/g, agileflowFolder);
+  // Replace folder placeholders with sanitized values
+  result = result.replace(/\{agileflow_folder\}/g, safeAgileflowFolder);
   result = result.replace(/\{project-root\}/g, '{project-root}'); // Keep as-is for runtime
 
   return result;