agileflow 3.4.3 → 4.0.0-alpha.2

package/lib/validate-args.js

@@ -1,213 +0,0 @@
-/**
- * AgileFlow CLI - Argument Validation Utilities
- *
- * Validation utilities for command-line arguments and options.
- */
-
-const {
-  isValidBranchName,
-  isValidStoryId,
-  isValidEpicId,
-  isValidFeatureName,
-  isValidProfileName,
-  isValidCommandName,
-  isValidSessionNickname,
-} = require('./validate-names');
-
-/**
- * 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 = {
-  isPositiveInteger,
-  parseIntBounded,
-  isValidOption,
-  validateArgs,
-};

package/lib/validate-commands.js

@@ -1,308 +0,0 @@
-/**
- * validate-commands.js - Command Validation for Shell Execution
- *
- * Validates and sanitizes commands before shell execution to prevent
- * command injection attacks. Uses allowlist approach for safe commands
- * and rejects dangerous shell metacharacters.
- *
- * Usage:
- *   const { validateCommand, ALLOWED_COMMANDS } = require('./validate-commands');
- *
- *   const result = validateCommand('npm test');
- *   if (result.ok) {
- *     // Safe to execute
- *     const { command, args } = result.data;
- *   } else {
- *     console.error(result.error);
- *   }
- */
-
-const { debugLog, sanitizeForShell } = require('./errors');
-
-/**
- * Allowed command prefixes for agent-loop execution
- * These are the only commands that can be executed
- */
-const ALLOWED_COMMANDS = {
-  // Package managers
-  npm: ['test', 'run', 'run-script'],
-  npx: ['jest', 'tsc', 'eslint', 'prettier', 'playwright', 'vitest'],
-  yarn: ['test', 'run'],
-  pnpm: ['test', 'run'],
-  bun: ['test', 'run'],
-
-  // Direct test runners (for projects not using npm scripts)
-  jest: true, // Allow all jest args
-  vitest: true,
-  mocha: true,
-  playwright: ['test'],
-
-  // Build tools
-  tsc: ['--noEmit', '--build', '-b'],
-
-  // Linters
-  eslint: true,
-  prettier: ['--check', '--write'],
-};
-
-/**
- * Dangerous shell metacharacters that could enable injection
- */
-const DANGEROUS_PATTERNS = [
-  /[;&|`$(){}]/g, // Shell operators, substitution
-  /\$\{/g, // Variable expansion
-  /\$\(/g, // Command substitution
-  /`[^`]*`/g, // Backtick substitution
-  />\s/g, // Redirection
-  /<\s/g, // Input redirection
-  /\n/g, // Newlines (could chain commands)
-  /\r/g, // Carriage return
-  /\\$/g, // Line continuation
-];
-
-/**
- * Parse a command string into executable and arguments
- * @param {string} cmdString - Full command string
- * @returns {{ executable: string, args: string[] }}
- */
-function parseCommand(cmdString) {
-  // Handle quoted arguments properly
-  const parts = [];
-  let current = '';
-  let inQuote = null;
-
-  for (let i = 0; i < cmdString.length; i++) {
-    const char = cmdString[i];
-
-    if (inQuote) {
-      if (char === inQuote) {
-        inQuote = null;
-      } else {
-        current += char;
-      }
-    } else if (char === '"' || char === "'") {
-      inQuote = char;
-    } else if (char === ' ' || char === '\t') {
-      if (current) {
-        parts.push(current);
-        current = '';
-      }
-    } else {
-      current += char;
-    }
-  }
-
-  if (current) {
-    parts.push(current);
-  }
-
-  return {
-    executable: parts[0] || '',
-    args: parts.slice(1),
-  };
-}
-
-/**
- * Check if an argument contains dangerous patterns
- * @param {string} arg - Argument to check
- * @returns {{ safe: boolean, pattern?: string }}
- */
-function checkArgSafety(arg) {
-  for (const pattern of DANGEROUS_PATTERNS) {
-    if (pattern.test(arg)) {
-      return { safe: false, pattern: pattern.source };
-    }
-  }
-  return { safe: true };
-}
-
-/**
- * Validate a command against the allowlist
- * @param {string} cmdString - Full command string to validate
- * @param {Object} [options={}] - Validation options
- * @param {boolean} [options.strict=true] - Require command in allowlist
- * @param {boolean} [options.logBlocked=true] - Log blocked commands
- * @returns {{ ok: boolean, data?: { command: string, args: string[] }, error?: string, severity?: string }}
- */
-function validateCommand(cmdString, options = {}) {
-  const { strict = true, logBlocked = true } = options;
-
-  // Must be a string
-  if (typeof cmdString !== 'string') {
-    return {
-      ok: false,
-      error: `Command must be a string, got ${typeof cmdString}`,
-      severity: 'high',
-    };
-  }
-
-  // Trim and check for empty
-  const trimmed = cmdString.trim();
-  if (!trimmed) {
-    return {
-      ok: false,
-      error: 'Command cannot be empty',
-      severity: 'medium',
-    };
-  }
-
-  // Parse the command
-  const { executable, args } = parseCommand(trimmed);
-
-  if (!executable) {
-    return {
-      ok: false,
-      error: 'No executable found in command',
-      severity: 'medium',
-    };
-  }
-
-  // Check executable against allowlist
-  const allowedSubcommands = ALLOWED_COMMANDS[executable];
-
-  if (strict && !allowedSubcommands) {
-    const error = `Command '${executable}' not in allowlist. Allowed: ${Object.keys(ALLOWED_COMMANDS).join(', ')}`;
-    if (logBlocked) {
-      debugLog('validateCommand', {
-        blocked: true,
-        command: executable,
-        reason: 'not_in_allowlist',
-      });
-    }
-    return {
-      ok: false,
-      error,
-      severity: 'high',
-    };
-  }
-
-  // If allowedSubcommands is an array, check the first argument
-  if (Array.isArray(allowedSubcommands) && args.length > 0) {
-    const subcommand = args[0];
-    if (!allowedSubcommands.includes(subcommand)) {
-      const error = `Subcommand '${subcommand}' not allowed for '${executable}'. Allowed: ${allowedSubcommands.join(', ')}`;
-      if (logBlocked) {
-        debugLog('validateCommand', {
-          blocked: true,
-          command: `${executable} ${subcommand}`,
-          reason: 'subcommand_not_allowed',
-        });
-      }
-      return {
-        ok: false,
-        error,
-        severity: 'high',
-      };
-    }
-  }
-
-  // Check all arguments for dangerous patterns
-  for (const arg of args) {
-    const argCheck = checkArgSafety(arg);
-    if (!argCheck.safe) {
-      const error = `Dangerous pattern in argument: '${arg}' matches ${argCheck.pattern}`;
-      if (logBlocked) {
-        debugLog('validateCommand', {
-          blocked: true,
-          command: executable,
-          arg,
-          pattern: argCheck.pattern,
-          reason: 'dangerous_pattern',
-        });
-      }
-      return {
-        ok: false,
-        error,
-        severity: 'critical',
-      };
-    }
-  }
-
-  // Additional check with sanitizeForShell for the full command
-  const fullCmdCheck = sanitizeForShell(trimmed, { context: 'command' });
-  if (!fullCmdCheck.ok) {
-    if (logBlocked) {
-      debugLog('validateCommand', {
-        blocked: true,
-        command: trimmed.slice(0, 50),
-        reason: 'shell_unsafe',
-        detected: fullCmdCheck.detected,
-      });
-    }
-    return {
-      ok: false,
-      error: fullCmdCheck.error,
-      severity: 'critical',
-    };
-  }
-
-  return {
-    ok: true,
-    data: {
-      command: executable,
-      args,
-    },
-  };
-}
-
-/**
- * Build a safe command array for spawn()
- * @param {string} cmdString - Command string
- * @param {Object} [options={}] - Options
- * @returns {{ ok: boolean, data?: { file: string, args: string[] }, error?: string }}
- */
-function buildSpawnArgs(cmdString, options = {}) {
-  const validation = validateCommand(cmdString, options);
-
-  if (!validation.ok) {
-    return validation;
-  }
-
-  return {
-    ok: true,
-    data: {
-      file: validation.data.command,
-      args: validation.data.args,
-    },
-  };
-}
-
-/**
- * Check if a command would be allowed (without modifying)
- * @param {string} cmdString - Command to check
- * @returns {boolean}
- */
-function isAllowedCommand(cmdString) {
-  return validateCommand(cmdString, { logBlocked: false }).ok;
-}
-
-/**
- * Get a list of all allowed command patterns
- * @returns {string[]}
- */
-function getAllowedCommandList() {
-  const list = [];
-
-  for (const [exe, subcommands] of Object.entries(ALLOWED_COMMANDS)) {
-    if (subcommands === true) {
-      list.push(`${exe} *`);
-    } else if (Array.isArray(subcommands)) {
-      for (const sub of subcommands) {
-        list.push(`${exe} ${sub}`);
-      }
-    }
-  }
-
-  return list;
-}
-
-module.exports = {
-  ALLOWED_COMMANDS,
-  DANGEROUS_PATTERNS,
-  validateCommand,
-  buildSpawnArgs,
-  isAllowedCommand,
-  getAllowedCommandList,
-  parseCommand,
-  checkArgSafety,
-};

package/lib/validate-names.js

@@ -1,143 +0,0 @@
-/**
- * AgileFlow CLI - Name Validation Utilities
- *
- * Validation patterns for names, IDs, and identifiers.
- * Pre-compiled regex patterns for optimal performance.
- */
-
-/**
- * Pre-compiled validation patterns for common input types.
- * All patterns use strict whitelisting approach.
- * Compiled once at module load for performance.
- */
-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/slashes, starts with letter
-  // Examples: babysit, story:list, agileflow:configure, research/ask
-  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);
-}
-
-module.exports = {
-  PATTERNS,
-  isValidBranchName,
-  isValidStoryId,
-  isValidEpicId,
-  isValidFeatureName,
-  isValidProfileName,
-  isValidCommandName,
-  isValidSessionNickname,
-  isValidMergeStrategy,
-};