agileflow 2.81.0 → 2.82.1

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 [![npm version](https://img.shields.io/npm/v/agileflow?color=brightgreen)](https://www.npmjs.com/package/agileflow)
-[![Commands](https://img.shields.io/badge/commands-68-blue)](docs/04-architecture/commands.md)
+[![Commands](https://img.shields.io/badge/commands-71-blue)](docs/04-architecture/commands.md)
 [![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-29-orange)](docs/04-architecture/subagents.md)
 [![Skills](https://img.shields.io/badge/skills-dynamic-purple)](docs/04-architecture/skills.md)
 
@@ -65,7 +65,7 @@ AgileFlow combines three proven methodologies:
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| [Commands](docs/04-architecture/commands.md) | 68 | Slash commands for agile workflows |
+| [Commands](docs/04-architecture/commands.md) | 71 | Slash commands for agile workflows |
 | [Agents/Experts](docs/04-architecture/subagents.md) | 29 | Specialized agents with self-improving knowledge bases |
 | [Skills](docs/04-architecture/skills.md) | Dynamic | Generated on-demand with `/agileflow:skill:create` |
 
@@ -76,7 +76,7 @@ AgileFlow combines three proven methodologies:
 Full documentation lives in [`docs/04-architecture/`](docs/04-architecture/):
 
 ### Reference
-- [Commands](docs/04-architecture/commands.md) - All 68 slash commands
+- [Commands](docs/04-architecture/commands.md) - All 71 slash commands
 - [Agents/Experts](docs/04-architecture/subagents.md) - 29 specialized agents with self-improving knowledge
 - [Skills](docs/04-architecture/skills.md) - Dynamic skill generator with MCP integration
 

package/lib/colors.js

@@ -0,0 +1,190 @@
+/**
+ * AgileFlow CLI - Shared Color Utilities
+ *
+ * Centralized ANSI color codes and formatting helpers.
+ * Uses 256-color palette for modern terminal support.
+ */
+
+/**
+ * ANSI color codes for terminal output.
+ * Includes standard colors, 256-color palette, and brand colors.
+ */
+const c = {
+  // Reset and modifiers
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  italic: '\x1b[3m',
+  underline: '\x1b[4m',
+
+  // Standard ANSI colors (8 colors)
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+
+  // Bright variants
+  brightBlack: '\x1b[90m',
+  brightRed: '\x1b[91m',
+  brightGreen: '\x1b[92m',
+  brightYellow: '\x1b[93m',
+  brightBlue: '\x1b[94m',
+  brightMagenta: '\x1b[95m',
+  brightCyan: '\x1b[96m',
+  brightWhite: '\x1b[97m',
+
+  // 256-color palette (vibrant, modern look)
+  mintGreen: '\x1b[38;5;158m', // Healthy/success states
+  peach: '\x1b[38;5;215m', // Warning states
+  coral: '\x1b[38;5;203m', // Critical/error states
+  lightGreen: '\x1b[38;5;194m', // Session healthy
+  lightYellow: '\x1b[38;5;228m', // Session warning
+  lightPink: '\x1b[38;5;210m', // Session critical
+  skyBlue: '\x1b[38;5;117m', // Directories/paths, ready states
+  lavender: '\x1b[38;5;147m', // Model info, story IDs
+  softGold: '\x1b[38;5;222m', // Cost/money
+  teal: '\x1b[38;5;80m', // Pending states
+  slate: '\x1b[38;5;103m', // Secondary info
+  rose: '\x1b[38;5;211m', // Blocked/critical accent
+  amber: '\x1b[38;5;214m', // WIP/in-progress accent
+  powder: '\x1b[38;5;153m', // Labels/headers
+
+  // Brand color (#e8683a - burnt orange/terracotta)
+  brand: '\x1b[38;2;232;104;58m',
+  orange: '\x1b[38;2;232;104;58m', // Alias for brand color
+
+  // Background colors
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+  bgBlue: '\x1b[44m',
+};
+
+/**
+ * Box drawing characters for tables and borders.
+ */
+const box = {
+  // Corners (rounded)
+  tl: '╭', // top-left
+  tr: '╮', // top-right
+  bl: '╰', // bottom-left
+  br: '╯', // bottom-right
+
+  // Lines
+  h: '─', // horizontal
+  v: '│', // vertical
+
+  // T-junctions
+  lT: '├', // left T
+  rT: '┤', // right T
+  tT: '┬', // top T
+  bT: '┴', // bottom T
+
+  // Cross
+  cross: '┼',
+
+  // Double line variants
+  dh: '═', // double horizontal
+  dv: '║', // double vertical
+};
+
+/**
+ * Status indicators with colors.
+ */
+const status = {
+  success: `${c.green}✓${c.reset}`,
+  warning: `${c.yellow}⚠️${c.reset}`,
+  error: `${c.red}✗${c.reset}`,
+  info: `${c.cyan}ℹ${c.reset}`,
+  pending: `${c.dim}○${c.reset}`,
+  inProgress: `${c.yellow}◐${c.reset}`,
+  done: `${c.green}●${c.reset}`,
+  blocked: `${c.red}◆${c.reset}`,
+};
+
+/**
+ * Wrap text with color codes.
+ *
+ * @param {string} text - Text to colorize
+ * @param {string} color - Color code from `c` object
+ * @returns {string} Colorized text
+ */
+function colorize(text, color) {
+  return `${color}${text}${c.reset}`;
+}
+
+/**
+ * Create a dim text string.
+ *
+ * @param {string} text - Text to dim
+ * @returns {string} Dimmed text
+ */
+function dim(text) {
+  return colorize(text, c.dim);
+}
+
+/**
+ * Create a bold text string.
+ *
+ * @param {string} text - Text to bold
+ * @returns {string} Bold text
+ */
+function bold(text) {
+  return colorize(text, c.bold);
+}
+
+/**
+ * Create success-colored text.
+ *
+ * @param {string} text - Text to color
+ * @returns {string} Green text
+ */
+function success(text) {
+  return colorize(text, c.green);
+}
+
+/**
+ * Create warning-colored text.
+ *
+ * @param {string} text - Text to color
+ * @returns {string} Yellow text
+ */
+function warning(text) {
+  return colorize(text, c.yellow);
+}
+
+/**
+ * Create error-colored text.
+ *
+ * @param {string} text - Text to color
+ * @returns {string} Red text
+ */
+function error(text) {
+  return colorize(text, c.red);
+}
+
+/**
+ * Create brand-colored text.
+ *
+ * @param {string} text - Text to color
+ * @returns {string} Brand-colored text (#e8683a)
+ */
+function brand(text) {
+  return colorize(text, c.brand);
+}
+
+module.exports = {
+  c,
+  box,
+  status,
+  colorize,
+  dim,
+  bold,
+  success,
+  warning,
+  error,
+  brand,
+};

package/lib/errors.js

@@ -0,0 +1,279 @@
+/**
+ * errors.js - Safe error handling wrappers
+ *
+ * Provides consistent error handling patterns across AgileFlow scripts.
+ * All wrappers return Result objects: { ok: boolean, data?: T, error?: string }
+ *
+ * Usage:
+ *   const { safeReadJSON, safeWriteJSON, safeExec } = require('../lib/errors');
+ *
+ *   const result = safeReadJSON('/path/to/file.json');
+ *   if (result.ok) {
+ *     console.log(result.data);
+ *   } else {
+ *     console.error(result.error);
+ *   }
+ */
+
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+// Debug logging (opt-in via AGILEFLOW_DEBUG=1)
+const DEBUG = process.env.AGILEFLOW_DEBUG === '1';
+
+function debugLog(operation, details) {
+  if (DEBUG) {
+    const timestamp = new Date().toISOString();
+    console.error(`[${timestamp}] [errors.js] ${operation}:`, JSON.stringify(details));
+  }
+}
+
+/**
+ * Safely read and parse a JSON file
+ * @param {string} filePath - Absolute path to JSON file
+ * @param {object} options - Optional settings
+ * @param {*} options.defaultValue - Value to return if file doesn't exist (makes missing file not an error)
+ * @returns {{ ok: boolean, data?: any, error?: string }}
+ */
+function safeReadJSON(filePath, options = {}) {
+  const { defaultValue } = options;
+
+  try {
+    if (!fs.existsSync(filePath)) {
+      if (defaultValue !== undefined) {
+        debugLog('safeReadJSON', { filePath, status: 'missing, using default' });
+        return { ok: true, data: defaultValue };
+      }
+      const error = `File not found: ${filePath}`;
+      debugLog('safeReadJSON', { filePath, error });
+      return { ok: false, error };
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const data = JSON.parse(content);
+    debugLog('safeReadJSON', { filePath, status: 'success' });
+    return { ok: true, data };
+  } catch (err) {
+    const error = `Failed to read JSON from ${filePath}: ${err.message}`;
+    debugLog('safeReadJSON', { filePath, error: err.message });
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Safely write data as JSON to a file
+ * @param {string} filePath - Absolute path to JSON file
+ * @param {any} data - Data to serialize as JSON
+ * @param {object} options - Optional settings
+ * @param {number} options.spaces - JSON indentation (default: 2)
+ * @param {boolean} options.createDir - Create parent directories if missing (default: false)
+ * @returns {{ ok: boolean, error?: string }}
+ */
+function safeWriteJSON(filePath, data, options = {}) {
+  const { spaces = 2, createDir = false } = options;
+
+  try {
+    if (createDir) {
+      const dir = require('path').dirname(filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+        debugLog('safeWriteJSON', { filePath, status: 'created directory', dir });
+      }
+    }
+
+    const content = JSON.stringify(data, null, spaces) + '\n';
+    fs.writeFileSync(filePath, content);
+    debugLog('safeWriteJSON', { filePath, status: 'success' });
+    return { ok: true };
+  } catch (err) {
+    const error = `Failed to write JSON to ${filePath}: ${err.message}`;
+    debugLog('safeWriteJSON', { filePath, error: err.message });
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Safely read a text file
+ * @param {string} filePath - Absolute path to file
+ * @param {object} options - Optional settings
+ * @param {string} options.defaultValue - Value to return if file doesn't exist
+ * @returns {{ ok: boolean, data?: string, error?: string }}
+ */
+function safeReadFile(filePath, options = {}) {
+  const { defaultValue } = options;
+
+  try {
+    if (!fs.existsSync(filePath)) {
+      if (defaultValue !== undefined) {
+        debugLog('safeReadFile', { filePath, status: 'missing, using default' });
+        return { ok: true, data: defaultValue };
+      }
+      const error = `File not found: ${filePath}`;
+      debugLog('safeReadFile', { filePath, error });
+      return { ok: false, error };
+    }
+
+    const data = fs.readFileSync(filePath, 'utf8');
+    debugLog('safeReadFile', { filePath, status: 'success' });
+    return { ok: true, data };
+  } catch (err) {
+    const error = `Failed to read file ${filePath}: ${err.message}`;
+    debugLog('safeReadFile', { filePath, error: err.message });
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Safely write text to a file
+ * @param {string} filePath - Absolute path to file
+ * @param {string} content - Content to write
+ * @param {object} options - Optional settings
+ * @param {boolean} options.createDir - Create parent directories if missing (default: false)
+ * @returns {{ ok: boolean, error?: string }}
+ */
+function safeWriteFile(filePath, content, options = {}) {
+  const { createDir = false } = options;
+
+  try {
+    if (createDir) {
+      const dir = require('path').dirname(filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+        debugLog('safeWriteFile', { filePath, status: 'created directory', dir });
+      }
+    }
+
+    fs.writeFileSync(filePath, content);
+    debugLog('safeWriteFile', { filePath, status: 'success' });
+    return { ok: true };
+  } catch (err) {
+    const error = `Failed to write file ${filePath}: ${err.message}`;
+    debugLog('safeWriteFile', { filePath, error: err.message });
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Safely execute a shell command
+ * @param {string} command - Shell command to execute
+ * @param {object} options - Optional settings
+ * @param {string} options.cwd - Working directory
+ * @param {number} options.timeout - Timeout in ms (default: 30000)
+ * @param {boolean} options.silent - Suppress stderr (default: false)
+ * @returns {{ ok: boolean, data?: string, error?: string, exitCode?: number }}
+ */
+function safeExec(command, options = {}) {
+  const { cwd = process.cwd(), timeout = 30000, silent = false } = options;
+
+  try {
+    const output = execSync(command, {
+      cwd,
+      encoding: 'utf8',
+      timeout,
+      stdio: silent ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'pipe', 'inherit'],
+    });
+    debugLog('safeExec', { command: command.slice(0, 50), status: 'success' });
+    return { ok: true, data: output.trim() };
+  } catch (err) {
+    const exitCode = err.status || 1;
+    const error = `Command failed (exit ${exitCode}): ${command.slice(0, 100)}${err.message ? ` - ${err.message}` : ''}`;
+    debugLog('safeExec', { command: command.slice(0, 50), error: err.message, exitCode });
+    return { ok: false, error, exitCode };
+  }
+}
+
+/**
+ * Safely check if a file or directory exists
+ * @param {string} path - Path to check
+ * @returns {{ ok: boolean, exists: boolean }}
+ */
+function safeExists(path) {
+  try {
+    const exists = fs.existsSync(path);
+    return { ok: true, exists };
+  } catch (err) {
+    debugLog('safeExists', { path, error: err.message });
+    return { ok: true, exists: false };
+  }
+}
+
+/**
+ * Safely create a directory
+ * @param {string} dirPath - Directory path to create
+ * @param {object} options - Optional settings
+ * @param {boolean} options.recursive - Create parent directories (default: true)
+ * @returns {{ ok: boolean, error?: string }}
+ */
+function safeMkdir(dirPath, options = {}) {
+  const { recursive = true } = options;
+
+  try {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive });
+      debugLog('safeMkdir', { dirPath, status: 'created' });
+    } else {
+      debugLog('safeMkdir', { dirPath, status: 'already exists' });
+    }
+    return { ok: true };
+  } catch (err) {
+    const error = `Failed to create directory ${dirPath}: ${err.message}`;
+    debugLog('safeMkdir', { dirPath, error: err.message });
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Wrap any function to catch errors and return Result
+ * @param {Function} fn - Function to wrap
+ * @param {string} operationName - Name for error messages
+ * @returns {Function} - Wrapped function returning { ok, data?, error? }
+ */
+function wrapSafe(fn, operationName = 'operation') {
+  return function (...args) {
+    try {
+      const result = fn.apply(this, args);
+      return { ok: true, data: result };
+    } catch (err) {
+      const error = `${operationName} failed: ${err.message}`;
+      debugLog('wrapSafe', { operationName, error: err.message });
+      return { ok: false, error };
+    }
+  };
+}
+
+/**
+ * Wrap an async function to catch errors and return Result
+ * @param {Function} fn - Async function to wrap
+ * @param {string} operationName - Name for error messages
+ * @returns {Function} - Wrapped async function returning { ok, data?, error? }
+ */
+function wrapSafeAsync(fn, operationName = 'operation') {
+  return async function (...args) {
+    try {
+      const result = await fn.apply(this, args);
+      return { ok: true, data: result };
+    } catch (err) {
+      const error = `${operationName} failed: ${err.message}`;
+      debugLog('wrapSafeAsync', { operationName, error: err.message });
+      return { ok: false, error };
+    }
+  };
+}
+
+module.exports = {
+  // Core safe operations
+  safeReadJSON,
+  safeWriteJSON,
+  safeReadFile,
+  safeWriteFile,
+  safeExec,
+  safeExists,
+  safeMkdir,
+
+  // Utility wrappers
+  wrapSafe,
+  wrapSafeAsync,
+
+  // Debug helper
+  debugLog,
+};

package/lib/paths.js

@@ -0,0 +1,99 @@
+/**
+ * AgileFlow CLI - Shared Path Utilities
+ *
+ * Centralized path resolution functions used across scripts.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Find the project root by looking for .agileflow directory.
+ * Walks up from current directory until .agileflow is found.
+ *
+ * @param {string} [startDir=process.cwd()] - Directory to start searching from
+ * @returns {string} Project root path, or startDir if not found
+ */
+function getProjectRoot(startDir = process.cwd()) {
+  let dir = startDir;
+  while (!fs.existsSync(path.join(dir, '.agileflow')) && dir !== '/') {
+    dir = path.dirname(dir);
+  }
+  return dir !== '/' ? dir : startDir;
+}
+
+/**
+ * Get the .agileflow directory path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to .agileflow directory
+ */
+function getAgileflowDir(rootDir) {
+  const root = rootDir || getProjectRoot();
+  return path.join(root, '.agileflow');
+}
+
+/**
+ * Get the .claude directory path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to .claude directory
+ */
+function getClaudeDir(rootDir) {
+  const root = rootDir || getProjectRoot();
+  return path.join(root, '.claude');
+}
+
+/**
+ * Get the docs directory path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to docs directory
+ */
+function getDocsDir(rootDir) {
+  const root = rootDir || getProjectRoot();
+  return path.join(root, 'docs');
+}
+
+/**
+ * Get the status.json path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to status.json
+ */
+function getStatusPath(rootDir) {
+  const root = rootDir || getProjectRoot();
+  return path.join(root, 'docs', '09-agents', 'status.json');
+}
+
+/**
+ * Get the session-state.json path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to session-state.json
+ */
+function getSessionStatePath(rootDir) {
+  const root = rootDir || getProjectRoot();
+  return path.join(root, 'docs', '09-agents', 'session-state.json');
+}
+
+/**
+ * Check if we're in an AgileFlow project.
+ *
+ * @param {string} [dir=process.cwd()] - Directory to check
+ * @returns {boolean} True if .agileflow directory exists
+ */
+function isAgileflowProject(dir = process.cwd()) {
+  const root = getProjectRoot(dir);
+  return fs.existsSync(path.join(root, '.agileflow'));
+}
+
+module.exports = {
+  getProjectRoot,
+  getAgileflowDir,
+  getClaudeDir,
+  getDocsDir,
+  getStatusPath,
+  getSessionStatePath,
+  isAgileflowProject,
+};