agileflow 2.89.2 → 2.90.0

package/tools/cli/installers/core/installer.js

@@ -8,10 +8,16 @@ const path = require('node:path');
 const fs = require('fs-extra');
 const chalk = require('chalk');
 const ora = require('ora');
-const yaml = require('js-yaml');
+const { safeLoad, safeDump } = require('../../../../lib/yaml-utils');
 const { injectContent } = require('../../lib/content-injector');
 const { sha256Hex, toPosixPath, safeTimestampForPath } = require('../../lib/utils');
 const { validatePath, PathValidationError } = require('../../../../lib/validate');
+const {
+  createTypedError,
+  getErrorCodeFromError,
+  attachErrorCode,
+} = require('../../../../lib/error-codes');
+const { setSecurePermissions, SECURE_FILE_MODE } = require('../../../../lib/smart-json-file');
 
 const TEXT_EXTENSIONS = new Set(['.md', '.yaml', '.yml', '.txt', '.json']);
 
@@ -188,6 +194,14 @@ class Installer {
       };
     } catch (error) {
       spinner.fail('Installation failed');
+
+      // Convert to typed error if not already
+      if (!error.errorCode) {
+        const errorCode = getErrorCodeFromError(error);
+        attachErrorCode(error, errorCode.code);
+        error.context = { directory, agileflowFolder };
+      }
+
       throw error;
     }
   }
@@ -490,13 +504,24 @@ class Installer {
         created_at: new Date().toISOString(),
       };
 
-      await fs.writeFile(configPath, yaml.dump(config), 'utf8');
+      await fs.writeFile(configPath, safeDump(config), 'utf8');
+      // Security: Set secure permissions (0o600) on config file
+      setSecurePermissions(configPath);
       return;
     }
 
     try {
       const existingContent = await fs.readFile(configPath, 'utf8');
-      const loaded = yaml.load(existingContent);
+      let loaded;
+      try {
+        loaded = safeLoad(existingContent);
+      } catch (parseErr) {
+        // Attach error code for YAML parse errors
+        throw createTypedError(`Failed to parse config.yaml: ${parseErr.message}`, 'EPARSE', {
+          cause: parseErr,
+          context: { configPath },
+        });
+      }
       const existing = loaded && typeof loaded === 'object' && !Array.isArray(loaded) ? loaded : {};
 
       const next = {
@@ -508,8 +533,15 @@ class Installer {
         updated_at: new Date().toISOString(),
       };
 
-      await fs.writeFile(configPath, yaml.dump(next), 'utf8');
-    } catch {
+      await fs.writeFile(configPath, safeDump(next), 'utf8');
+      // Security: Set secure permissions (0o600) on config file
+      setSecurePermissions(configPath);
+    } catch (err) {
+      // If it's a typed parse error and not forcing, re-throw
+      if (err.errorCode === 'EPARSE' && !options.force) {
+        throw err;
+      }
+
       if (options.force) {
         const config = {
           version: packageJson.version,
@@ -519,7 +551,9 @@ class Installer {
           created_at: new Date().toISOString(),
         };
 
-        await fs.writeFile(configPath, yaml.dump(config), 'utf8');
+        await fs.writeFile(configPath, safeDump(config), 'utf8');
+        // Security: Set secure permissions (0o600) on config file
+        setSecurePermissions(configPath);
       }
     }
   }
@@ -550,13 +584,24 @@ class Installer {
         docs_folder: docsFolder || 'docs',
       };
 
-      await fs.writeFile(manifestPath, yaml.dump(manifest), 'utf8');
+      await fs.writeFile(manifestPath, safeDump(manifest), 'utf8');
+      // Security: Set secure permissions (0o600) on manifest file
+      setSecurePermissions(manifestPath);
       return;
     }
 
     try {
       const existingContent = await fs.readFile(manifestPath, 'utf8');
-      const loaded = yaml.load(existingContent);
+      let loaded;
+      try {
+        loaded = safeLoad(existingContent);
+      } catch (parseErr) {
+        // Attach error code for YAML parse errors
+        throw createTypedError(`Failed to parse manifest.yaml: ${parseErr.message}`, 'EPARSE', {
+          cause: parseErr,
+          context: { manifestPath },
+        });
+      }
       const existing = loaded && typeof loaded === 'object' && !Array.isArray(loaded) ? loaded : {};
 
       const manifest = {
@@ -571,8 +616,15 @@ class Installer {
         docs_folder: docsFolder || existing.docs_folder || 'docs',
       };
 
-      await fs.writeFile(manifestPath, yaml.dump(manifest), 'utf8');
-    } catch {
+      await fs.writeFile(manifestPath, safeDump(manifest), 'utf8');
+      // Security: Set secure permissions (0o600) on manifest file
+      setSecurePermissions(manifestPath);
+    } catch (err) {
+      // If it's a typed parse error and not forcing, re-throw
+      if (err.errorCode === 'EPARSE' && !options.force) {
+        throw err;
+      }
+
       if (options.force) {
         const manifest = {
           version: packageJson.version,
@@ -585,7 +637,9 @@ class Installer {
           docs_folder: docsFolder || 'docs',
         };
 
-        await fs.writeFile(manifestPath, yaml.dump(manifest), 'utf8');
+        await fs.writeFile(manifestPath, safeDump(manifest), 'utf8');
+        // Security: Set secure permissions (0o600) on manifest file
+        setSecurePermissions(manifestPath);
       }
     }
   }
@@ -790,7 +844,16 @@ class Installer {
         status.path = agileflowDir;
 
         const manifestContent = await fs.readFile(manifestPath, 'utf8');
-        const manifest = yaml.load(manifestContent);
+        let manifest;
+        try {
+          manifest = safeLoad(manifestContent);
+        } catch (parseErr) {
+          // Attach error code for YAML parse errors
+          throw createTypedError(`Failed to parse manifest.yaml: ${parseErr.message}`, 'EPARSE', {
+            cause: parseErr,
+            context: { manifestPath },
+          });
+        }
 
         status.version = manifest.version;
         status.ides = manifest.ides || [];

package/tools/cli/installers/ide/_interface.js

@@ -0,0 +1,238 @@
+/**
+ * _interface.js - IDE Handler Interface
+ *
+ * Defines the formal contract that all IDE handlers must implement.
+ * This interface ensures consistency across IDE installers and
+ * enables validation at registration time.
+ *
+ * Usage:
+ *   const { IdeHandlerInterface, validateHandler } = require('./_interface');
+ *
+ *   class MyIdeSetup extends BaseIdeSetup {
+ *     // Implement required methods
+ *   }
+ *
+ *   // In IdeManager.loadHandlers():
+ *   const validationResult = validateHandler(handler);
+ *   if (!validationResult.valid) {
+ *     throw new Error(`Invalid handler: ${validationResult.errors.join(', ')}`);
+ *   }
+ */
+
+/**
+ * Required methods that every IDE handler must implement
+ * @type {Object.<string, {required: boolean, description: string, signature: string}>}
+ */
+const REQUIRED_METHODS = {
+  setup: {
+    required: true,
+    description: 'Main setup method to configure the IDE',
+    signature:
+      'async setup(projectDir: string, agileflowDir: string, options?: object): Promise<object>',
+  },
+  cleanup: {
+    required: true,
+    description: 'Cleanup old IDE configuration',
+    signature: 'async cleanup(projectDir: string): Promise<void>',
+  },
+  detect: {
+    required: true,
+    description: 'Detect if this IDE is configured in the project',
+    signature: 'async detect(projectDir: string): Promise<boolean>',
+  },
+};
+
+/**
+ * Required properties that every IDE handler must have
+ * @type {Object.<string, {required: boolean, description: string, type: string}>}
+ */
+const REQUIRED_PROPERTIES = {
+  name: {
+    required: true,
+    description: 'Unique identifier for the IDE (lowercase)',
+    type: 'string',
+  },
+  displayName: {
+    required: true,
+    description: 'Human-readable name for display',
+    type: 'string',
+  },
+  configDir: {
+    required: true,
+    description: 'Configuration directory name (e.g., ".cursor", ".claude")',
+    type: 'string',
+  },
+};
+
+/**
+ * Optional methods that handlers may implement
+ * @type {Object.<string, {description: string, signature: string}>}
+ */
+const OPTIONAL_METHODS = {
+  setAgileflowFolder: {
+    description: 'Set the AgileFlow folder name',
+    signature: 'setAgileflowFolder(folderName: string): void',
+  },
+  setDocsFolder: {
+    description: 'Set the docs folder name',
+    signature: 'setDocsFolder(folderName: string): void',
+  },
+};
+
+/**
+ * Validate that a handler implements all required methods and properties
+ * @param {object} handler - IDE handler instance to validate
+ * @returns {{valid: boolean, errors: string[], warnings: string[]}}
+ */
+function validateHandler(handler) {
+  const errors = [];
+  const warnings = [];
+
+  if (!handler) {
+    return { valid: false, errors: ['Handler is null or undefined'], warnings: [] };
+  }
+
+  // Check required properties
+  for (const [propName, propDef] of Object.entries(REQUIRED_PROPERTIES)) {
+    if (propDef.required) {
+      const value = handler[propName];
+
+      if (value === undefined || value === null) {
+        errors.push(`Missing required property: ${propName} (${propDef.description})`);
+      } else if (propDef.type && typeof value !== propDef.type) {
+        errors.push(`Property ${propName} must be of type ${propDef.type}, got ${typeof value}`);
+      }
+    }
+  }
+
+  // Check required methods
+  for (const [methodName, methodDef] of Object.entries(REQUIRED_METHODS)) {
+    if (methodDef.required) {
+      const method = handler[methodName];
+
+      if (typeof method !== 'function') {
+        errors.push(`Missing required method: ${methodName}() - ${methodDef.description}`);
+      }
+    }
+  }
+
+  // Check for optional methods (just warnings)
+  for (const [methodName, methodDef] of Object.entries(OPTIONAL_METHODS)) {
+    if (typeof handler[methodName] !== 'function') {
+      warnings.push(`Optional method not implemented: ${methodName}() - ${methodDef.description}`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Get a summary of the interface requirements
+ * @returns {string} Human-readable summary
+ */
+function getInterfaceSummary() {
+  const lines = ['IDE Handler Interface Requirements:', ''];
+
+  lines.push('Required Properties:');
+  for (const [name, def] of Object.entries(REQUIRED_PROPERTIES)) {
+    lines.push(`  - ${name}: ${def.type} - ${def.description}`);
+  }
+
+  lines.push('');
+  lines.push('Required Methods:');
+  for (const [name, def] of Object.entries(REQUIRED_METHODS)) {
+    lines.push(`  - ${name}()`);
+    lines.push(`    Signature: ${def.signature}`);
+    lines.push(`    Purpose: ${def.description}`);
+    lines.push('');
+  }
+
+  lines.push('Optional Methods:');
+  for (const [name, def] of Object.entries(OPTIONAL_METHODS)) {
+    lines.push(`  - ${name}(): ${def.description}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * IDE Handler Interface - Abstract base that defines the contract
+ * This is for documentation purposes; actual handlers extend BaseIdeSetup
+ */
+class IdeHandlerInterface {
+  /**
+   * @param {string} name - Unique identifier (lowercase)
+   * @param {string} displayName - Human-readable name
+   * @param {string} configDir - Configuration directory name
+   */
+  constructor(name, displayName, configDir) {
+    if (this.constructor === IdeHandlerInterface) {
+      throw new Error('IdeHandlerInterface is abstract and cannot be instantiated directly');
+    }
+
+    this.name = name;
+    this.displayName = displayName;
+    this.configDir = configDir;
+  }
+
+  /**
+   * Main setup method - MUST be implemented
+   * @param {string} projectDir - Project directory
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @param {Object} [options] - Setup options
+   * @returns {Promise<{success: boolean, commands?: number, agents?: number}>}
+   * @abstract
+   */
+  async setup(projectDir, agileflowDir, options = {}) {
+    throw new Error('setup() must be implemented by subclass');
+  }
+
+  /**
+   * Cleanup IDE configuration - MUST be implemented
+   * @param {string} projectDir - Project directory
+   * @returns {Promise<void>}
+   * @abstract
+   */
+  async cleanup(projectDir) {
+    throw new Error('cleanup() must be implemented by subclass');
+  }
+
+  /**
+   * Detect if IDE is configured - MUST be implemented
+   * @param {string} projectDir - Project directory
+   * @returns {Promise<boolean>}
+   * @abstract
+   */
+  async detect(projectDir) {
+    throw new Error('detect() must be implemented by subclass');
+  }
+
+  /**
+   * Set AgileFlow folder name - OPTIONAL
+   * @param {string} folderName - Folder name
+   */
+  setAgileflowFolder(folderName) {
+    // Optional - implement if needed
+  }
+
+  /**
+   * Set docs folder name - OPTIONAL
+   * @param {string} folderName - Folder name
+   */
+  setDocsFolder(folderName) {
+    // Optional - implement if needed
+  }
+}
+
+module.exports = {
+  IdeHandlerInterface,
+  validateHandler,
+  getInterfaceSummary,
+  REQUIRED_METHODS,
+  REQUIRED_PROPERTIES,
+  OPTIONAL_METHODS,
+};

package/tools/cli/installers/ide/codex.js

@@ -14,7 +14,7 @@ const path = require('node:path');
 const os = require('node:os');
 const fs = require('fs-extra');
 const chalk = require('chalk');
-const yaml = require('js-yaml');
+const { safeLoad, yaml } = require('../../../../lib/yaml-utils');
 const { BaseIdeSetup } = require('./_base-ide');
 const { parseFrontmatter } = require('../../../../scripts/lib/frontmatter-parser');
 
@@ -120,7 +120,7 @@ ${codexHeader}${bodyContent}`;
     const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
     if (frontmatterMatch) {
       try {
-        const frontmatter = yaml.load(frontmatterMatch[1]);
+        const frontmatter = safeLoad(frontmatterMatch[1]);
         if (frontmatter.description) {
           description = frontmatter.description;
         }

package/tools/cli/installers/ide/manager.js

@@ -2,11 +2,13 @@
  * AgileFlow CLI - IDE Manager
  *
  * Manages IDE-specific installers and configuration.
+ * Validates handlers implement the required interface before registration.
  */
 
 const fs = require('fs-extra');
 const path = require('node:path');
 const chalk = require('chalk');
+const { validateHandler } = require('./_interface');
 
 /**
  * IDE Manager - handles IDE-specific setup
@@ -68,6 +70,19 @@ class IdeManager {
 
           if (HandlerClass && typeof HandlerClass === 'function') {
             const instance = new HandlerClass();
+
+            // Validate handler implements required interface
+            const validation = validateHandler(instance);
+
+            if (!validation.valid) {
+              console.log(
+                chalk.yellow(
+                  `  Warning: IDE handler ${file} failed validation: ${validation.errors.join(', ')}`
+                )
+              );
+              continue; // Skip invalid handlers
+            }
+
             if (instance.name) {
               this.handlers.set(instance.name, instance);
             }