agileflow 2.89.1 → 2.89.3

package/scripts/ralph-loop.js

@@ -664,7 +664,7 @@ function handleLoop(rootDir) {
     }
 
     // Evaluate discretion conditions
-    let discretionResults = [];
+    const discretionResults = [];
     if (hasDiscretionConditions) {
       console.log('');
       console.log(`${c.blue}Evaluating discretion conditions...${c.reset}`);

package/tools/cli/commands/config.js

@@ -7,7 +7,7 @@
 const chalk = require('chalk');
 const path = require('node:path');
 const fs = require('fs-extra');
-const yaml = require('js-yaml');
+const { safeLoad, safeDump } = require('../../../lib/yaml-utils');
 const { Installer } = require('../installers/core/installer');
 const { IdeManager } = require('../installers/ide/manager');
 const { displayLogo, displaySection, success, warning, error, info } = require('../lib/ui');
@@ -194,7 +194,7 @@ async function handleSet(directory, status, manifestPath, key, value) {
 
   // Read current manifest
   const manifestContent = await fs.readFile(manifestPath, 'utf8');
-  const manifest = yaml.load(manifestContent);
+  const manifest = safeLoad(manifestContent);
 
   // Track if we need to update IDE configs
   let needsIdeUpdate = false;
@@ -247,7 +247,7 @@ async function handleSet(directory, status, manifestPath, key, value) {
   manifest.updated_at = new Date().toISOString();
 
   // Write manifest
-  await fs.writeFile(manifestPath, yaml.dump(manifest), 'utf8');
+  await fs.writeFile(manifestPath, safeDump(manifest), 'utf8');
   success('Configuration updated');
 
   // Update IDE configs if needed

package/tools/cli/commands/doctor.js

@@ -21,6 +21,13 @@ const {
 const { IdeManager } = require('../installers/ide/manager');
 const { getCurrentVersion } = require('../lib/version-checker');
 const { ErrorHandler } = require('../lib/error-handler');
+const {
+  ErrorCodes,
+  getErrorCodeFromError,
+  getSuggestedFix,
+  isRecoverable,
+} = require('../../../lib/error-codes');
+const { safeDump } = require('../../../lib/yaml-utils');
 
 const installer = new Installer();
 
@@ -88,6 +95,7 @@ module.exports = {
         issues++;
         repairs.push({
           type: 'missing-manifest',
+          errorCode: 'ENOENT',
           message: 'Recreate missing manifest.yaml',
           fix: async () => {
             info('Recreating manifest.yaml...');
@@ -95,7 +103,6 @@ module.exports = {
             const cfgDir = path.join(status.path, '_cfg');
             await fs.ensureDir(cfgDir);
 
-            const yaml = require('js-yaml');
             const manifest = {
               version: packageJson.version,
               installed_at: new Date().toISOString(),
@@ -107,7 +114,7 @@ module.exports = {
               docs_folder: 'docs',
             };
 
-            await fs.writeFile(manifestPath, yaml.dump(manifest), 'utf8');
+            await fs.writeFile(manifestPath, safeDump(manifest), 'utf8');
             success('Created manifest.yaml');
           },
         });
@@ -142,6 +149,7 @@ module.exports = {
           warnings++;
           repairs.push({
             type: 'invalid-file-index',
+            errorCode: 'EPARSE',
             message: 'Recreate files.json safe-update index',
             fix: async () => {
               await createProtectedFileIndex(status.path, fileIndexPath);
@@ -154,6 +162,7 @@ module.exports = {
         warnings++;
         repairs.push({
           type: 'missing-file-index',
+          errorCode: 'ENOENT',
           message: 'Create files.json safe-update index',
           fix: async () => {
             await createProtectedFileIndex(status.path, fileIndexPath);
@@ -196,6 +205,7 @@ module.exports = {
       if (missingCore) {
         repairs.push({
           type: 'missing-core',
+          errorCode: 'EEMPTYDIR',
           message: 'Reinstall missing core content',
           fix: async () => {
             info('Reinstalling core content...');
@@ -241,6 +251,7 @@ module.exports = {
             warnings++;
             repairs.push({
               type: 'missing-ide-config',
+              errorCode: 'ENODIR',
               message: `Reinstall ${ideName} configuration`,
               fix: async () => {
                 info(`Reinstalling ${ideName} configuration...`);
@@ -267,6 +278,7 @@ module.exports = {
             warnings++;
             repairs.push({
               type: 'orphaned-config',
+              errorCode: 'ECONFLICT',
               message: `Remove orphaned ${ideName} configuration`,
               fix: async () => {
                 info(`Removing orphaned ${ideName} configuration...`);
@@ -291,7 +303,13 @@ module.exports = {
           try {
             await repair.fix();
           } catch (err) {
+            // Use error codes for better diagnosis
+            const codeData = getErrorCodeFromError(err);
             error(`Failed to ${repair.message.toLowerCase()}: ${err.message}`);
+            if (codeData.code !== 'EUNKNOWN') {
+              console.log(chalk.dim(`  Error code: ${codeData.code}`));
+              console.log(chalk.dim(`  Suggestion: ${codeData.suggestedFix}`));
+            }
           }
         }
 
@@ -300,6 +318,16 @@ module.exports = {
       } else if (repairs.length > 0 && !options.fix) {
         console.log();
         info(`Found ${repairs.length} fixable issue(s). Run with --fix to auto-repair.`);
+
+        // Show summary of fixable issues with error codes
+        console.log(chalk.bold('\nFixable Issues:'));
+        for (const repair of repairs) {
+          const errorCode = repair.errorCode || 'ECONFIG';
+          const codeData = ErrorCodes[errorCode] || ErrorCodes.ECONFIG;
+          console.log(
+            `  ${chalk.yellow('!')} ${repair.message} ${chalk.dim(`[${codeData.code}]`)}`
+          );
+        }
       }
 
       // Print summary

package/tools/cli/commands/list.js

@@ -7,7 +7,7 @@
 const chalk = require('chalk');
 const path = require('node:path');
 const fs = require('fs-extra');
-const yaml = require('js-yaml');
+const { safeLoad } = require('../../../lib/yaml-utils');
 const { Installer } = require('../installers/core/installer');
 const { displayLogo, displaySection, success, warning, info } = require('../lib/ui');
 const {
@@ -233,7 +233,7 @@ async function listExperts(agileflowPath) {
 
     try {
       const content = await fs.readFile(expertiseFile, 'utf8');
-      const parsed = yaml.load(content);
+      const parsed = safeLoad(content);
 
       experts.push({
         name: entry.name,

package/tools/cli/commands/uninstall.js

@@ -78,12 +78,12 @@ module.exports = {
         // Update the manifest to remove this IDE
         const manifestPath = path.join(status.path, '_cfg', 'manifest.yaml');
         if (await fs.pathExists(manifestPath)) {
-          const yaml = require('js-yaml');
+          const { safeLoad, safeDump } = require('../../../lib/yaml-utils');
           const manifestContent = await fs.readFile(manifestPath, 'utf8');
-          const manifest = yaml.load(manifestContent);
+          const manifest = safeLoad(manifestContent);
           manifest.ides = (manifest.ides || []).filter(ide => ide !== ideName);
           manifest.updated_at = new Date().toISOString();
-          await fs.writeFile(manifestPath, yaml.dump(manifest), 'utf8');
+          await fs.writeFile(manifestPath, safeDump(manifest), 'utf8');
           success('Updated manifest');
         }
 

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

@@ -8,10 +8,15 @@ 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 TEXT_EXTENSIONS = new Set(['.md', '.yaml', '.yml', '.txt', '.json']);
 
@@ -188,6 +193,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 +503,22 @@ class Installer {
         created_at: new Date().toISOString(),
       };
 
-      await fs.writeFile(configPath, yaml.dump(config), 'utf8');
+      await fs.writeFile(configPath, safeDump(config), 'utf8');
       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 +530,13 @@ class Installer {
         updated_at: new Date().toISOString(),
       };
 
-      await fs.writeFile(configPath, yaml.dump(next), 'utf8');
-    } catch {
+      await fs.writeFile(configPath, safeDump(next), 'utf8');
+    } 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 +546,7 @@ class Installer {
           created_at: new Date().toISOString(),
         };
 
-        await fs.writeFile(configPath, yaml.dump(config), 'utf8');
+        await fs.writeFile(configPath, safeDump(config), 'utf8');
       }
     }
   }
@@ -550,13 +577,22 @@ class Installer {
         docs_folder: docsFolder || 'docs',
       };
 
-      await fs.writeFile(manifestPath, yaml.dump(manifest), 'utf8');
+      await fs.writeFile(manifestPath, safeDump(manifest), 'utf8');
       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 +607,13 @@ 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');
+    } 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 +626,7 @@ class Installer {
           docs_folder: docsFolder || 'docs',
         };
 
-        await fs.writeFile(manifestPath, yaml.dump(manifest), 'utf8');
+        await fs.writeFile(manifestPath, safeDump(manifest), 'utf8');
       }
     }
   }
@@ -790,7 +831,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);
             }