agileflow 2.84.2 → 2.86.0

package/tools/cli/commands/uninstall.js

@@ -10,6 +10,7 @@ const fs = require('fs-extra');
 const { Installer } = require('../installers/core/installer');
 const { IdeManager } = require('../installers/ide/manager');
 const { displayLogo, displaySection, success, warning, error, confirm } = require('../lib/ui');
+const { ErrorHandler } = require('../lib/error-handler');
 
 const installer = new Installer();
 const ideManager = new IdeManager();
@@ -138,11 +139,13 @@ module.exports = {
 
       process.exit(0);
     } catch (err) {
-      console.error(chalk.red('Uninstall failed:'), err.message);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
+      const handler = new ErrorHandler('uninstall');
+      handler.critical(
+        'Uninstall failed',
+        'Check file permissions',
+        'sudo npx agileflow uninstall --force',
+        err
+      );
     }
   },
 };

package/tools/cli/commands/update.js

@@ -22,6 +22,7 @@ const {
 } = require('../lib/ui');
 const { createDocsStructure, getDocsFolderName } = require('../lib/docs-setup');
 const { getLatestVersion } = require('../lib/npm-utils');
+const { ErrorHandler } = require('../lib/error-handler');
 
 const installer = new Installer();
 const ideManager = new IdeManager();
@@ -76,9 +77,12 @@ module.exports = {
       const status = await installer.getStatus(directory);
 
       if (!status.installed) {
-        warning('No AgileFlow installation found');
-        console.log(chalk.dim(`\nRun 'npx agileflow setup' to set up AgileFlow\n`));
-        process.exit(1);
+        const handler = new ErrorHandler('update');
+        handler.warning(
+          'No AgileFlow installation found',
+          'Initialize AgileFlow first',
+          'npx agileflow setup'
+        );
       }
 
       displaySection('Updating AgileFlow', `Current version: ${status.version}`);
@@ -179,8 +183,12 @@ module.exports = {
       const coreResult = await installer.install(config, { force: options.force });
 
       if (!coreResult.success) {
-        error('Update failed');
-        process.exit(1);
+        const handler = new ErrorHandler('update');
+        handler.warning(
+          'Update failed',
+          'Try running doctor to diagnose issues',
+          'npx agileflow doctor --fix'
+        );
       }
 
       success('Updated core content');
@@ -237,11 +245,13 @@ module.exports = {
 
       process.exit(0);
     } catch (err) {
-      console.error(chalk.red('Update failed:'), err.message);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
+      const handler = new ErrorHandler('update');
+      handler.critical(
+        'Update failed',
+        'Check network connection and disk space',
+        'npx agileflow doctor',
+        err
+      );
     }
   },
 };

package/tools/cli/lib/content-injector.js

@@ -202,6 +202,80 @@ function injectContent(content, context = {}) {
   return result;
 }
 
+// =============================================================================
+// Section Processing Functions (Progressive Disclosure)
+// =============================================================================
+
+/**
+ * Extract section names from content
+ * @param {string} content - Content with section markers
+ * @returns {string[]} Array of section names
+ */
+function extractSectionNames(content) {
+  const sectionPattern = /<!-- SECTION: (\w+[-\w]*) -->/g;
+  const sections = [];
+  let match;
+  while ((match = sectionPattern.exec(content)) !== null) {
+    sections.push(match[1]);
+  }
+  return sections;
+}
+
+/**
+ * Filter content to only include specified sections
+ * Sections are marked with: <!-- SECTION: name --> ... <!-- END_SECTION -->
+ *
+ * @param {string} content - Content with section markers
+ * @param {string[]} activeSections - Sections to include (empty = include all)
+ * @returns {string} Content with only active sections
+ */
+function filterSections(content, activeSections = []) {
+  // If no active sections specified, include all content
+  if (!activeSections || activeSections.length === 0) {
+    return content;
+  }
+
+  // Pattern matches: <!-- SECTION: name --> content <!-- END_SECTION -->
+  const sectionPattern = /<!-- SECTION: (\w+[-\w]*) -->([\s\S]*?)<!-- END_SECTION -->/g;
+
+  return content.replace(sectionPattern, (match, sectionName, sectionContent) => {
+    if (activeSections.includes(sectionName)) {
+      // Keep the section content, remove the markers
+      return sectionContent;
+    }
+    // Remove the entire section
+    return '';
+  });
+}
+
+/**
+ * Remove all section markers but keep content
+ * Used when no filtering is needed but markers should be cleaned
+ *
+ * @param {string} content - Content with section markers
+ * @returns {string} Content without section markers
+ */
+function stripSectionMarkers(content) {
+  // Remove section start markers
+  let result = content.replace(/<!-- SECTION: \w+[-\w]* -->\n?/g, '');
+  // Remove section end markers
+  result = result.replace(/<!-- END_SECTION -->\n?/g, '');
+  return result;
+}
+
+/**
+ * Check if content has section markers
+ * @param {string} content - Content to check
+ * @returns {boolean} True if content has sections
+ */
+function hasSections(content) {
+  return /<!-- SECTION: \w+[-\w]* -->/.test(content);
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
 /**
  * Check if content has any template variables
  * @param {string} content - Content to check
@@ -263,4 +337,10 @@ module.exports = {
   injectContent,
   hasPlaceholders,
   getPlaceholderDocs,
+
+  // Section processing (progressive disclosure)
+  extractSectionNames,
+  filterSections,
+  stripSectionMarkers,
+  hasSections,
 };

package/tools/cli/lib/error-handler.js

@@ -0,0 +1,173 @@
+/**
+ * error-handler.js - Centralized Error Handling with Actionable Guidance
+ *
+ * Provides three-tier error handling:
+ * - INFO: Non-blocking issues (does not exit)
+ * - WARNING: Issues that should be addressed (exit 1)
+ * - CRITICAL: Severe errors (exit 1 + stack trace if DEBUG=1)
+ *
+ * Error output format: "X <problem> | Action: <what to do> | Run: <command>"
+ */
+
+const { c } = require('../../../lib/colors');
+
+class ErrorHandler {
+  /**
+   * Create an ErrorHandler instance
+   * @param {string} commandName - Name of the command using this handler
+   */
+  constructor(commandName = 'agileflow') {
+    this.commandName = commandName;
+  }
+
+  /**
+   * Format error with actionable guidance
+   * Output: "X <problem> | Action: <what to do> | Run: <command>"
+   *
+   * @param {string} message - The error message describing the problem
+   * @param {string} [actionText] - What the user should do to fix it
+   * @param {string} [commandHint] - Command to run to fix it
+   * @returns {string} Formatted error string
+   */
+  formatError(message, actionText, commandHint) {
+    let output = `${c.red}\u2716${c.reset} ${message}`;
+    if (actionText) {
+      output += ` ${c.dim}|${c.reset} ${c.cyan}Action:${c.reset} ${actionText}`;
+    }
+    if (commandHint) {
+      output += ` ${c.dim}|${c.reset} ${c.green}Run:${c.reset} ${c.bold}${commandHint}${c.reset}`;
+    }
+    return output;
+  }
+
+  /**
+   * Format warning message (yellow indicator)
+   * @param {string} message - The warning message
+   * @param {string} [actionText] - What the user should do
+   * @param {string} [commandHint] - Command to run
+   * @returns {string} Formatted warning string
+   */
+  formatWarning(message, actionText, commandHint) {
+    let output = `${c.yellow}\u26A0${c.reset}  ${message}`;
+    if (actionText) {
+      output += ` ${c.dim}|${c.reset} ${c.cyan}Action:${c.reset} ${actionText}`;
+    }
+    if (commandHint) {
+      output += ` ${c.dim}|${c.reset} ${c.green}Run:${c.reset} ${c.bold}${commandHint}${c.reset}`;
+    }
+    return output;
+  }
+
+  /**
+   * INFO: Non-blocking issue, continue execution (does NOT exit)
+   * Use for informational messages about issues that don't prevent operation.
+   *
+   * @param {string} message - The info message
+   * @param {string} [actionText] - Optional action hint
+   * @param {string} [commandHint] - Optional command hint
+   */
+  info(message, actionText, commandHint) {
+    console.log(this.formatWarning(message, actionText, commandHint));
+    // Does NOT exit - allows continuation
+  }
+
+  /**
+   * WARNING: Issue that should be addressed (exit 1)
+   * Use for problems that prevent the operation from completing properly.
+   *
+   * @param {string} message - The warning message
+   * @param {string} [actionText] - What the user should do
+   * @param {string} [commandHint] - Command to run to fix it
+   */
+  warning(message, actionText, commandHint) {
+    console.error(this.formatError(message, actionText, commandHint));
+    process.exit(1);
+  }
+
+  /**
+   * CRITICAL: Severe error (exit 1 + stack trace if DEBUG=1)
+   * Use for unexpected errors, crashes, or severe failures.
+   *
+   * @param {string} message - The error message
+   * @param {string} [actionText] - What the user should do
+   * @param {string} [commandHint] - Command to run
+   * @param {Error} [error] - Original error object for stack trace
+   */
+  critical(message, actionText, commandHint, error) {
+    console.error(this.formatError(message, actionText, commandHint));
+    if (process.env.DEBUG === '1' && error?.stack) {
+      console.error(`\n${c.dim}Stack trace:${c.reset}`);
+      console.error(c.dim + error.stack + c.reset);
+    }
+    process.exit(1);
+  }
+
+  /**
+   * Convenience method: Get formatted error string without exiting
+   * Useful for collecting multiple errors before displaying.
+   *
+   * @param {string} message - The error message
+   * @param {string} [actionText] - What the user should do
+   * @param {string} [commandHint] - Command to run
+   * @returns {string} Formatted error string
+   */
+  errorWithAction(message, actionText, commandHint) {
+    return this.formatError(message, actionText, commandHint);
+  }
+
+  /**
+   * Convenience method: Get formatted warning string without exiting
+   *
+   * @param {string} message - The warning message
+   * @param {string} [actionText] - What the user should do
+   * @param {string} [commandHint] - Command to run
+   * @returns {string} Formatted warning string
+   */
+  warningWithAction(message, actionText, commandHint) {
+    return this.formatWarning(message, actionText, commandHint);
+  }
+
+  /**
+   * Display multiple issues at once, then exit with appropriate code
+   * Useful for validation that collects all errors before reporting.
+   *
+   * @param {Array<{type: 'info'|'warning'|'error', message: string, action?: string, command?: string}>} issues
+   * @returns {boolean} True if there were errors/warnings (would normally exit)
+   */
+  reportIssues(issues) {
+    let hasErrors = false;
+    let hasWarnings = false;
+
+    for (const issue of issues) {
+      if (issue.type === 'error') {
+        console.error(this.formatError(issue.message, issue.action, issue.command));
+        hasErrors = true;
+      } else if (issue.type === 'warning') {
+        console.error(this.formatWarning(issue.message, issue.action, issue.command));
+        hasWarnings = true;
+      } else {
+        console.log(this.formatWarning(issue.message, issue.action, issue.command));
+      }
+    }
+
+    if (hasErrors || hasWarnings) {
+      process.exit(1);
+    }
+
+    return hasErrors || hasWarnings;
+  }
+}
+
+/**
+ * Create a pre-configured ErrorHandler instance
+ * @param {string} commandName - Name of the command
+ * @returns {ErrorHandler} New ErrorHandler instance
+ */
+function createErrorHandler(commandName) {
+  return new ErrorHandler(commandName);
+}
+
+module.exports = {
+  ErrorHandler,
+  createErrorHandler,
+};

package/tools/cli/lib/ui.js

@@ -9,6 +9,7 @@ const inquirer = require('inquirer');
 const path = require('node:path');
 const fs = require('node:fs');
 const { IdeManager } = require('../installers/ide/manager');
+const { BRAND_HEX } = require('../../../lib/colors');
 
 // Load package.json for version
 const packageJsonPath = path.join(__dirname, '..', '..', '..', 'package.json');
@@ -25,7 +26,7 @@ function displayLogo() {
 ██╔══██║██║   ██║██║██║     ██╔══╝  ██╔══╝  ██║     ██║   ██║██║███╗██║
 ██║  ██║╚██████╔╝██║███████╗███████╗██║     ███████╗╚██████╔╝╚███╔███╔╝
 ╚═╝  ╚═╝ ╚═════╝ ╚═╝╚══════╝╚══════╝╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝ `;
-  console.log(chalk.hex('#e8683a')(logo));
+  console.log(chalk.hex(BRAND_HEX)(logo));
   console.log(chalk.dim(`  AgileFlow v${packageJson.version} - AI-Driven Agile Development\n`));
 }
 
@@ -35,7 +36,7 @@ function displayLogo() {
  * @param {string} subtitle - Optional subtitle
  */
 function displaySection(title, subtitle = null) {
-  console.log(chalk.bold.hex('#e8683a')(`\n${title}`));
+  console.log(chalk.bold.hex(BRAND_HEX)(`\n${title}`));
   if (subtitle) {
     console.log(chalk.dim(subtitle));
   }