agileflow 2.82.0 → 2.82.1

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,
+};

package/lib/validate.js

@@ -0,0 +1,337 @@
+/**
+ * AgileFlow CLI - Input Validation Utilities
+ *
+ * Centralized validation patterns and helpers to prevent
+ * command injection and invalid input handling.
+ */
+
+/**
+ * Validation patterns for common input types.
+ * All patterns use strict whitelisting approach.
+ */
+const PATTERNS = {
+  // Git branch: alphanumeric, underscores, hyphens, forward slashes
+  // Examples: main, feature/US-0001, session-1, my_branch
+  branchName: /^[a-zA-Z0-9][a-zA-Z0-9_/-]*$/,
+
+  // Story ID: US-0001 to US-99999
+  storyId: /^US-\d{4,5}$/,
+
+  // Epic ID: EP-0001 to EP-99999
+  epicId: /^EP-\d{4,5}$/,
+
+  // Feature name: lowercase with hyphens, starts with letter
+  // Examples: damage-control, status-line, archival
+  featureName: /^[a-z][a-z0-9-]*$/,
+
+  // Profile name: alphanumeric with underscores/hyphens, starts with letter
+  // Examples: default, my-profile, dev_config
+  profileName: /^[a-zA-Z][a-zA-Z0-9_-]*$/,
+
+  // Command name: alphanumeric with hyphens/colons, starts with letter
+  // Examples: babysit, story:list, agileflow:configure
+  commandName: /^[a-zA-Z][a-zA-Z0-9:-]*$/,
+
+  // Session nickname: alphanumeric with hyphens/underscores
+  // Examples: auth-work, feature_1, main
+  sessionNickname: /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/,
+
+  // Merge strategy: squash or merge
+  // Examples: squash, merge
+  mergeStrategy: /^(squash|merge)$/,
+};
+
+/**
+ * Validate a git branch name.
+ * @param {string} name - Branch name to validate
+ * @returns {boolean} True if valid
+ */
+function isValidBranchName(name) {
+  if (!name || typeof name !== 'string') return false;
+  if (name.length > 255) return false; // Git limit
+  if (name.startsWith('-')) return false; // Prevent flag injection
+  if (name.includes('..')) return false; // Prevent path traversal
+  if (name.endsWith('.lock')) return false; // Reserved
+  return PATTERNS.branchName.test(name);
+}
+
+/**
+ * Validate a story ID (US-XXXX format).
+ * @param {string} id - Story ID to validate
+ * @returns {boolean} True if valid
+ */
+function isValidStoryId(id) {
+  if (!id || typeof id !== 'string') return false;
+  return PATTERNS.storyId.test(id);
+}
+
+/**
+ * Validate an epic ID (EP-XXXX format).
+ * @param {string} id - Epic ID to validate
+ * @returns {boolean} True if valid
+ */
+function isValidEpicId(id) {
+  if (!id || typeof id !== 'string') return false;
+  return PATTERNS.epicId.test(id);
+}
+
+/**
+ * Validate a feature name.
+ * @param {string} name - Feature name to validate
+ * @returns {boolean} True if valid
+ */
+function isValidFeatureName(name) {
+  if (!name || typeof name !== 'string') return false;
+  if (name.length > 50) return false;
+  return PATTERNS.featureName.test(name);
+}
+
+/**
+ * Validate a profile name.
+ * @param {string} name - Profile name to validate
+ * @returns {boolean} True if valid
+ */
+function isValidProfileName(name) {
+  if (!name || typeof name !== 'string') return false;
+  if (name.length > 50) return false;
+  return PATTERNS.profileName.test(name);
+}
+
+/**
+ * Validate a command name.
+ * @param {string} name - Command name to validate
+ * @returns {boolean} True if valid
+ */
+function isValidCommandName(name) {
+  if (!name || typeof name !== 'string') return false;
+  if (name.length > 100) return false;
+  return PATTERNS.commandName.test(name);
+}
+
+/**
+ * Validate a session nickname.
+ * @param {string} name - Nickname to validate
+ * @returns {boolean} True if valid
+ */
+function isValidSessionNickname(name) {
+  if (!name || typeof name !== 'string') return false;
+  if (name.length > 50) return false;
+  return PATTERNS.sessionNickname.test(name);
+}
+
+/**
+ * Validate a merge strategy (squash or merge).
+ * @param {string} strategy - Strategy to validate
+ * @returns {boolean} True if valid
+ */
+function isValidMergeStrategy(strategy) {
+  if (!strategy || typeof strategy !== 'string') return false;
+  return PATTERNS.mergeStrategy.test(strategy);
+}
+
+/**
+ * Validate that a value is a positive integer within bounds.
+ * @param {any} val - Value to validate
+ * @param {number} min - Minimum allowed value (inclusive)
+ * @param {number} max - Maximum allowed value (inclusive)
+ * @returns {boolean} True if valid positive integer in range
+ */
+function isPositiveInteger(val, min = 1, max = Number.MAX_SAFE_INTEGER) {
+  const num = typeof val === 'string' ? parseInt(val, 10) : val;
+  if (!Number.isInteger(num)) return false;
+  return num >= min && num <= max;
+}
+
+/**
+ * Parse and validate an integer with bounds.
+ * @param {any} val - Value to parse
+ * @param {number} defaultVal - Default if invalid
+ * @param {number} min - Minimum allowed value
+ * @param {number} max - Maximum allowed value
+ * @returns {number} Parsed integer or default
+ */
+function parseIntBounded(val, defaultVal, min = 1, max = Number.MAX_SAFE_INTEGER) {
+  const num = typeof val === 'string' ? parseInt(val, 10) : val;
+  if (!Number.isInteger(num) || num < min || num > max) {
+    return defaultVal;
+  }
+  return num;
+}
+
+/**
+ * Validate an option key against an allowed whitelist.
+ * @param {string} key - Option key to validate
+ * @param {string[]} allowedKeys - Array of allowed keys
+ * @returns {boolean} True if key is in whitelist
+ */
+function isValidOption(key, allowedKeys) {
+  if (!key || typeof key !== 'string') return false;
+  if (!Array.isArray(allowedKeys)) return false;
+  return allowedKeys.includes(key);
+}
+
+/**
+ * Validate and sanitize CLI arguments for known option types.
+ * Returns validated args object or null if critical validation fails.
+ *
+ * @param {string[]} args - Raw process.argv slice
+ * @param {Object} schema - Schema defining expected options
+ * @returns {{ ok: boolean, data?: Object, error?: string }}
+ *
+ * @example
+ * const schema = {
+ *   branch: { type: 'branchName', required: true },
+ *   max: { type: 'positiveInt', min: 1, max: 100, default: 20 },
+ *   profile: { type: 'profileName', default: 'default' }
+ * };
+ * const result = validateArgs(args, schema);
+ */
+function validateArgs(args, schema) {
+  const result = {};
+  const errors = [];
+
+  // Parse args into key-value pairs
+  const parsed = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const [key, ...valueParts] = arg.slice(2).split('=');
+      const value = valueParts.length > 0 ? valueParts.join('=') : args[++i];
+      parsed[key] = value;
+    }
+  }
+
+  // Validate each schema field
+  for (const [field, config] of Object.entries(schema)) {
+    const value = parsed[field];
+
+    // Check required
+    if (config.required && (value === undefined || value === null)) {
+      errors.push(`Missing required option: --${field}`);
+      continue;
+    }
+
+    // Use default if not provided
+    if (value === undefined || value === null) {
+      if (config.default !== undefined) {
+        result[field] = config.default;
+      }
+      continue;
+    }
+
+    // Validate by type
+    switch (config.type) {
+      case 'branchName':
+        if (!isValidBranchName(value)) {
+          errors.push(`Invalid branch name: ${value}`);
+        } else {
+          result[field] = value;
+        }
+        break;
+
+      case 'storyId':
+        if (!isValidStoryId(value)) {
+          errors.push(`Invalid story ID: ${value} (expected US-XXXX)`);
+        } else {
+          result[field] = value;
+        }
+        break;
+
+      case 'epicId':
+        if (!isValidEpicId(value)) {
+          errors.push(`Invalid epic ID: ${value} (expected EP-XXXX)`);
+        } else {
+          result[field] = value;
+        }
+        break;
+
+      case 'featureName':
+        if (!isValidFeatureName(value)) {
+          errors.push(`Invalid feature name: ${value}`);
+        } else {
+          result[field] = value;
+        }
+        break;
+
+      case 'profileName':
+        if (!isValidProfileName(value)) {
+          errors.push(`Invalid profile name: ${value}`);
+        } else {
+          result[field] = value;
+        }
+        break;
+
+      case 'commandName':
+        if (!isValidCommandName(value)) {
+          errors.push(`Invalid command name: ${value}`);
+        } else {
+          result[field] = value;
+        }
+        break;
+
+      case 'sessionNickname':
+        if (!isValidSessionNickname(value)) {
+          errors.push(`Invalid session nickname: ${value}`);
+        } else {
+          result[field] = value;
+        }
+        break;
+
+      case 'positiveInt': {
+        const min = config.min || 1;
+        const max = config.max || Number.MAX_SAFE_INTEGER;
+        if (!isPositiveInteger(value, min, max)) {
+          errors.push(`Invalid integer for ${field}: ${value} (expected ${min}-${max})`);
+          result[field] = config.default;
+        } else {
+          result[field] = parseInt(value, 10);
+        }
+        break;
+      }
+
+      case 'enum':
+        if (!config.values.includes(value)) {
+          errors.push(
+            `Invalid value for ${field}: ${value} (expected: ${config.values.join(', ')})`
+          );
+        } else {
+          result[field] = value;
+        }
+        break;
+
+      case 'boolean':
+        result[field] = value === 'true' || value === '1' || value === true;
+        break;
+
+      case 'string':
+        // Basic string - just store it (caller should validate further if needed)
+        result[field] = String(value);
+        break;
+
+      default:
+        result[field] = value;
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, error: errors.join('; ') };
+  }
+
+  return { ok: true, data: result };
+}
+
+module.exports = {
+  PATTERNS,
+  isValidBranchName,
+  isValidStoryId,
+  isValidEpicId,
+  isValidFeatureName,
+  isValidProfileName,
+  isValidCommandName,
+  isValidSessionNickname,
+  isValidMergeStrategy,
+  isPositiveInteger,
+  parseIntBounded,
+  isValidOption,
+  validateArgs,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.82.0",
+  "version": "2.82.1",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",
@@ -32,6 +32,7 @@
     "tools/",
     "src/",
     "scripts/",
+    "lib/",
     "LICENSE",
     "README.md"
   ],

package/scripts/ralph-loop.js

@@ -674,7 +674,9 @@ function handleLoop(rootDir) {
         const result = evaluateDiscretionCondition(condition, rootDir, ctx);
         discretionResults.push({ condition, ...result });
         const marker = result.passed ? `${c.green}✓` : `${c.yellow}⏳`;
-        console.log(`  ${marker} **${condition.replace(/\*\*/g, '')}**: ${result.message}${c.reset}`);
+        console.log(
+          `  ${marker} **${condition.replace(/\*\*/g, '')}**: ${result.message}${c.reset}`
+        );
       }
 
       // Track which conditions have been verified
@@ -688,8 +690,7 @@ function handleLoop(rootDir) {
     }
 
     // Check if all verification modes passed
-    const allDiscretionPassed =
-      !hasDiscretionConditions || discretionResults.every(r => r.passed);
+    const allDiscretionPassed = !hasDiscretionConditions || discretionResults.every(r => r.passed);
     const canComplete =
       testResult.passed &&
       (!visualMode || screenshotResult.passed) &&
@@ -848,7 +849,9 @@ function handleCLI() {
         const verified = loop.conditions_verified
           ? `${c.green}yes${c.reset}`
           : `${c.yellow}no${c.reset}`;
-        console.log(`  Discretion Conditions: ${loop.conditions.length} (All Verified: ${verified})`);
+        console.log(
+          `  Discretion Conditions: ${loop.conditions.length} (All Verified: ${verified})`
+        );
         for (const result of loop.condition_results || []) {
           const mark = result.passed ? `${c.green}✓${c.reset}` : `${c.yellow}⏳${c.reset}`;
           console.log(`    ${mark} ${result.condition.replace(/\*\*/g, '')}`);
@@ -953,8 +956,7 @@ function handleCLI() {
     }
 
     // Get conditions from metadata if not provided via CLI
-    const allConditions =
-      conditions.length > 0 ? conditions : getDiscretionConditions(rootDir);
+    const allConditions = conditions.length > 0 ? conditions : getDiscretionConditions(rootDir);
 
     // Initialize loop state
     const state = getSessionState(rootDir);