@arclabs561/ai-visual-test 0.5.1 → 0.7.4

package/src/utils/intent-recognizer.mjs

@@ -0,0 +1,201 @@
+/**
+ * Intent Recognition for Browser Automation
+ * 
+ * Parses natural language tasks into structured intents.
+ * Simple keyword-based recognition - fast and sufficient for most cases.
+ * 
+ * Research Context:
+ * - Intent recognition accuracy >85% is often cited as critical for browser automation agents
+ * - Ambiguous tasks require disambiguation (e.g., "Buy this product" = add to cart + checkout)
+ * - Multi-step tasks need workflow decomposition
+ * 
+ * Implementation:
+ * - We use simple keyword-based recognition (fast, <1ms)
+ * - LLM-based recognition was considered but adds latency (>1s) and cost without clear benefit for current use cases.
+ * - Complex disambiguation happens during action execution, not intent parsing
+ * 
+ * See docs/research/IMPLEMENTATION_VS_RESEARCH.md for detailed research context.
+ * 
+ * @module intent-recognizer
+ */
+
+
+/**
+ * Recognized intent types
+ */
+export const INTENT_TYPES = {
+  NAVIGATE: 'navigate',
+  FILL_FORM: 'fill_form',
+  VALIDATE: 'validate',
+  EXPLORE: 'explore',
+  PLAY_GAME: 'play_game',
+  CLICK: 'click',
+  WAIT: 'wait',
+  EXTRACT: 'extract',
+  UNKNOWN: 'unknown'
+};
+
+/**
+ * Recognize intent from natural language task
+ * 
+ * @param {string} task - Natural language task description
+ * @returns {Promise<Object>} Recognized intent with confidence
+ */
+export async function recognizeIntent(task) {
+  // Simple keyword-based recognition - fast and sufficient
+  // LLM-based recognition adds latency and cost without clear benefit
+  return recognizeIntentKeyword(task);
+}
+
+
+/**
+ * Keyword-based intent recognition (fallback)
+ */
+function recognizeIntentKeyword(task) {
+  const lower = task.toLowerCase();
+  
+  // Navigate
+  if (lower.match(/\b(navigate|go to|visit|open|browse to|take me to)\b/)) {
+    const target = extractTarget(task); // Use original task text, not lowercased
+    return {
+      intent: INTENT_TYPES.NAVIGATE,
+      confidence: 0.8,
+      subIntents: [],
+      parameters: target ? { target } : {},
+      reasoning: 'Keyword-based recognition: navigation intent detected'
+    };
+  }
+  
+  // Fill form
+  if (lower.match(/\b(fill|complete|submit|enter|type)\b.*\b(form|field|input)\b/)) {
+    return {
+      intent: INTENT_TYPES.FILL_FORM,
+      confidence: 0.8,
+      subIntents: [],
+      parameters: {},
+      reasoning: 'Keyword-based recognition: form filling intent detected'
+    };
+  }
+  
+  // Validate
+  if (lower.match(/\b(check|validate|verify|test|ensure|confirm)\b/)) {
+    return {
+      intent: INTENT_TYPES.VALIDATE,
+      confidence: 0.8,
+      subIntents: [],
+      parameters: {},
+      reasoning: 'Keyword-based recognition: validation intent detected'
+    };
+  }
+  
+  // Explore
+  if (lower.match(/\b(explore|try|find|search|look for|discover)\b/)) {
+    return {
+      intent: INTENT_TYPES.EXPLORE,
+      confidence: 0.8,
+      subIntents: [],
+      parameters: {},
+      reasoning: 'Keyword-based recognition: exploration intent detected'
+    };
+  }
+  
+  // Play game
+  if (lower.match(/\b(play|game|score|level)\b/)) {
+    return {
+      intent: INTENT_TYPES.PLAY_GAME,
+      confidence: 0.8,
+      subIntents: [],
+      parameters: {},
+      reasoning: 'Keyword-based recognition: game playing intent detected'
+    };
+  }
+  
+  // Click
+  if (lower.match(/\b(click|press|tap|select)\b/)) {
+    const target = extractTarget(task); // Use original task text, not lowercased
+    return {
+      intent: INTENT_TYPES.CLICK,
+      confidence: 0.8,
+      subIntents: [],
+      parameters: target ? { target } : {},
+      reasoning: 'Keyword-based recognition: click intent detected'
+    };
+  }
+  
+  // Wait
+  if (lower.match(/\b(wait|pause|delay)\b/)) {
+    return {
+      intent: INTENT_TYPES.WAIT,
+      confidence: 0.8,
+      subIntents: [],
+      parameters: {},
+      reasoning: 'Keyword-based recognition: wait intent detected'
+    };
+  }
+  
+  // Extract
+  if (lower.match(/\b(extract|get|read|find|identify)\b.*\b(information|data|value|text)\b/)) {
+    return {
+      intent: INTENT_TYPES.EXTRACT,
+      confidence: 0.8,
+      subIntents: [],
+      parameters: {},
+      reasoning: 'Keyword-based recognition: extraction intent detected'
+    };
+  }
+  
+  // Unknown
+  return {
+    intent: INTENT_TYPES.UNKNOWN,
+    confidence: 0.5,
+    subIntents: [],
+    parameters: {},
+    reasoning: 'Keyword-based recognition: intent unclear'
+  };
+}
+
+/**
+ * Extract target from task text
+ */
+function extractTarget(text) {
+  // Try to extract quoted strings or specific targets
+  const quoted = text.match(/"([^"]+)"/) || text.match(/'([^']+)'/);
+  if (quoted) return quoted[1];
+  
+  // Extract after "to" or "for"
+  const afterTo = text.match(/\b(?:to|for)\s+([a-z\s]+)/i);
+  if (afterTo) return afterTo[1].trim();
+  
+  return null;
+}
+
+/**
+ * Batch recognize intents
+ */
+export async function batchRecognizeIntents(tasks, _screenshotPaths = [], _options = {}) {
+  const results = await Promise.all(
+    tasks.map((task) => 
+      recognizeIntent(task)
+    )
+  );
+  
+  const total = results.length;
+  const recognized = results.filter(r => r.intent !== INTENT_TYPES.UNKNOWN).length;
+  const accuracy = recognized / total;
+  
+  const intentDistribution = results.reduce((acc, r) => {
+    acc[r.intent] = (acc[r.intent] || 0) + 1;
+    return acc;
+  }, {});
+  
+  return {
+    total,
+    recognized,
+    accuracy,
+    intentDistribution,
+    results,
+    recommendation: accuracy >= 0.85
+      ? 'Intent recognition accuracy meets target (>85%)'
+      : 'Intent recognition accuracy below target. Consider improving prompts or adding more training examples.'
+  };
+}

package/src/utils/log-sanitizer.mjs

@@ -0,0 +1,165 @@
+/**
+ * Log Sanitization Utilities
+ * 
+ * Provides log sanitization to prevent information disclosure in production logs.
+ * Removes sensitive data like API keys, full paths, and long prompts.
+ */
+
+import { basename } from 'path';
+
+/**
+ * Fields that should never be logged (sensitive data)
+ */
+const SENSITIVE_FIELDS = [
+  'apiKey',
+  'token',
+  'password',
+  'secret',
+  'credential',
+  'authorization',
+  'x-api-key',
+  'x-goog-api-key',
+  'bearer'
+];
+
+/**
+ * Maximum length for logged strings (prevents log flooding)
+ */
+const MAX_LOG_LENGTH = 200;
+
+/**
+ * Sanitize data for logging
+ * 
+ * Removes sensitive fields, truncates long strings, and sanitizes paths.
+ * 
+ * @param {unknown} data - Data to sanitize
+ * @param {Object} [options={}] - Sanitization options
+ * @param {boolean} [options.removeSensitive=true] - Remove sensitive fields
+ * @param {number} [options.maxLength=200] - Maximum string length
+ * @param {boolean} [options.sanitizePaths=true] - Sanitize file paths
+ * @returns {unknown} Sanitized data
+ */
+export function sanitizeForLogging(data, options = {}) {
+  const {
+    removeSensitive = true,
+    maxLength = MAX_LOG_LENGTH,
+    sanitizePaths = true
+  } = options;
+
+  // Handle null/undefined
+  if (data === null || data === undefined) {
+    return data;
+  }
+
+  // Handle primitives
+  if (typeof data !== 'object') {
+    return sanitizePrimitive(data, maxLength);
+  }
+
+  // Handle arrays
+  if (Array.isArray(data)) {
+    return data.map(item => sanitizeForLogging(item, options));
+  }
+
+  // Handle objects
+  const sanitized = {};
+  for (const [key, value] of Object.entries(data)) {
+    // Remove sensitive fields
+    if (removeSensitive && isSensitiveField(key)) {
+      sanitized[key] = '[REDACTED]';
+      continue;
+    }
+
+    // Sanitize paths
+    if (sanitizePaths && isPathField(key)) {
+      sanitized[key] = typeof value === 'string' ? basename(value) : value;
+      continue;
+    }
+
+    // Recursively sanitize nested objects
+    if (typeof value === 'object' && value !== null) {
+      sanitized[key] = sanitizeForLogging(value, options);
+      continue;
+    }
+
+    // Sanitize primitives
+    sanitized[key] = sanitizePrimitive(value, maxLength);
+  }
+
+  return sanitized;
+}
+
+/**
+ * Check if a field name indicates sensitive data
+ * 
+ * @param {string} fieldName - Field name to check
+ * @returns {boolean} True if field is sensitive
+ */
+function isSensitiveField(fieldName) {
+  const lower = fieldName.toLowerCase();
+  return SENSITIVE_FIELDS.some(sensitive => lower.includes(sensitive.toLowerCase()));
+}
+
+/**
+ * Check if a field name indicates a file path
+ * 
+ * @param {string} fieldName - Field name to check
+ * @returns {boolean} True if field is a path
+ */
+function isPathField(fieldName) {
+  const lower = fieldName.toLowerCase();
+  return lower.includes('path') || lower.includes('file') || lower.includes('dir');
+}
+
+/**
+ * Sanitize a primitive value
+ * 
+ * @param {unknown} value - Value to sanitize
+ * @param {number} maxLength - Maximum length
+ * @returns {unknown} Sanitized value
+ */
+function sanitizePrimitive(value, maxLength) {
+  if (typeof value === 'string') {
+    if (value.length > maxLength) {
+      return value.substring(0, maxLength) + '...';
+    }
+    return value;
+  }
+  return value;
+}
+
+/**
+ * Sanitize error object for logging
+ * 
+ * @param {Error} error - Error object
+ * @param {Object} [options={}] - Sanitization options
+ * @returns {Object} Sanitized error
+ */
+export function sanitizeErrorForLogging(error, options = {}) {
+  if (!error || typeof error !== 'object') {
+    return error;
+  }
+
+  const sanitized = {
+    name: error.name,
+    message: sanitizePrimitive(error.message, options.maxLength || MAX_LOG_LENGTH)
+  };
+
+  // Include stack trace only in debug mode
+  if (options.includeStack && error.stack) {
+    sanitized.stack = sanitizePrimitive(error.stack, options.maxStackLength || 500);
+  }
+
+  // Sanitize error details if present
+  if (error.details && typeof error.details === 'object') {
+    sanitized.details = sanitizeForLogging(error.details, options);
+  }
+
+  // Include code if present (useful for debugging)
+  if (error.code) {
+    sanitized.code = error.code;
+  }
+
+  return sanitized;
+}
+

package/src/utils/path-validator.mjs

@@ -0,0 +1,88 @@
+/**
+ * Path Validation Utilities
+ * 
+ * Provides secure path validation to prevent path traversal attacks.
+ * 
+ * NOTE: The primary validateFilePath() function is in src/validation.mjs.
+ * This module provides additional utilities for path validation.
+ * 
+ * @deprecated validateFilePath() - Use validateFilePath() from '../validation.mjs' instead
+ * This function is kept for backward compatibility but delegates to the main implementation.
+ */
+
+import { resolve, normalize, basename } from 'path';
+import { existsSync } from 'fs';
+import { ValidationError } from '../errors.mjs';
+import { validateFilePath as validateFilePathMain } from '../validation.mjs';
+
+/**
+ * Validates and normalizes a file path to prevent path traversal attacks
+ * 
+ * @deprecated Use validateFilePath() from '../validation.mjs' instead
+ * @param {string} userPath - User-provided file path
+ * @param {string} baseDir - Base directory (optional, defaults to process.cwd())
+ * @returns {string} - Resolved, normalized path
+ * @throws {ValidationError} - If path is invalid or outside base directory
+ */
+export function validateFilePath(userPath, baseDir = process.cwd()) {
+  // Validate empty string before delegating (main implementation also checks, but we want consistent error)
+  if (typeof userPath !== 'string' || !userPath.trim()) {
+    throw new ValidationError('File path must be a non-empty string', null, {
+      received: typeof userPath
+    });
+  }
+  
+  // Delegate to main implementation for consistency
+  return validateFilePathMain(userPath, { baseDir });
+}
+
+/**
+ * Sanitize file path for error messages (prevents information disclosure)
+ * 
+ * @param {string} fullPath - Full file path
+ * @param {number} maxDepth - Maximum directory depth to show (default: 2)
+ * @returns {string} - Sanitized path showing only last N components
+ */
+export function sanitizePathForError(fullPath, maxDepth = 2) {
+  if (typeof fullPath !== 'string') {
+    return '[invalid path]';
+  }
+  
+  const parts = fullPath.split('/').filter(p => p);
+  if (parts.length <= maxDepth) {
+    return fullPath;
+  }
+  
+  // Show only last maxDepth parts
+  return '.../' + parts.slice(-maxDepth).join('/');
+}
+
+/**
+ * Validate that a path is within allowed directories
+ * 
+ * @param {string} userPath - User-provided path
+ * @param {string[]} allowedDirs - Array of allowed base directories
+ * @returns {string} - Resolved path if valid
+ * @throws {ValidationError} - If path is outside all allowed directories
+ */
+export function validatePathInAllowedDirs(userPath, allowedDirs) {
+  if (!Array.isArray(allowedDirs) || allowedDirs.length === 0) {
+    throw new ValidationError('allowedDirs must be a non-empty array');
+  }
+  
+  for (const allowedDir of allowedDirs) {
+    try {
+      const resolved = validateFilePath(userPath, allowedDir);
+      return resolved;
+    } catch {
+      // Try next allowed directory
+      continue;
+    }
+  }
+  
+  // Path not in any allowed directory
+  throw new ValidationError('File path is outside allowed directories', userPath, {
+    allowedDirs
+  });
+}
+