@pilaf/framework 1.2.2 → 1.3.0

package/lib/helpers/correlation.js

@@ -0,0 +1,325 @@
+/**
+ * CorrelationUtils - Server-side correlation for player actions
+ *
+ * Provides utilities for correlating player actions with server-side
+ * confirmation events. Works with or without EventObserver:
+ *
+ * - WITH EventObserver: Event-driven correlation (faster, more reliable)
+ * - WITHOUT EventObserver: Timeout-based fallback (simple, compatible)
+ *
+ * Responsibilities (MECE):
+ * - ONLY: Wait for server confirmation of player actions
+ * - NOT: Execute player actions (use bot methods directly)
+ * - NOT: Parse server logs (EventObserver/LogParser's responsibility)
+ * - NOT: Collect logs (LogCollector's responsibility)
+ */
+
+/**
+ * Simple glob pattern matcher
+ *
+ * Supports:
+ * - * : matches any sequence of characters
+ * - ? : matches any single character
+ *
+ * @private
+ * @param {string} text - Text to match against
+ * @param {string} pattern - Glob pattern (e.g., "*placed*", "entity.*")
+ * @returns {boolean} True if pattern matches
+ */
+function _matchPattern(text, pattern) {
+  if (!text || !pattern) return false;
+
+  // Convert glob pattern to regex
+  // First escape all special regex characters except * and ?
+  let regexPattern = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&');  // Escape special regex chars
+
+  // Then convert * and ? to their regex equivalents
+  regexPattern = '^' + regexPattern
+    .replace(/\*/g, '.*')   // * becomes .*
+    .replace(/\?/g, '.') + '$';  // ? becomes .
+
+  const regex = new RegExp(regexPattern, 'i');  // Case-insensitive
+  return regex.test(text);
+}
+
+/**
+ * Wait for server confirmation of a player action
+ *
+ * This is the main correlation utility. It waits for a server log event
+ * that matches the expected pattern, confirming that the player's action
+ * was processed by the server.
+ *
+ * Supports two modes:
+ * 1. Event-driven mode (with EventObserver): Listens for matching events
+ * 2. Timeout mode (without EventObserver): Waits for specified timeout
+ *
+ * @param {Object} storyRunner - StoryRunner instance (provides access to backends)
+ * @param {Object} options - Options
+ * @param {string} options.pattern - Glob pattern to match in server logs
+ * @param {number} [options.timeout=5000] - Timeout in milliseconds
+ * @param {boolean} [options.invert=false] - If true, wait for ABSENCE of pattern
+ * @param {string} [options.player] - Player name to filter events (optional)
+ * @returns {Promise<Object|null>} Matching event object, or null if timeout/inverted
+ *
+ * @example
+ * // Wait for block placement confirmation
+ * await CorrelationUtils.waitForServerConfirmation(storyRunner, {
+ *   pattern: '*Cannot place block*',
+ *   invert: true,
+ *   timeout: 3000
+ * });
+ *
+ * @example
+ * // Wait for command execution
+ * const event = await CorrelationUtils.waitForServerConfirmation(storyRunner, {
+ *   pattern: '*issued command* /gamemode*',
+ *   timeout: 5000
+ * });
+ */
+async function waitForServerConfirmation(storyRunner, options) {
+  const {
+    pattern = '*',
+    timeout = 5000,
+    invert = false,
+    player = null
+  } = options || {};
+
+  // Try EventObserver mode first (event-driven, faster)
+  const eventObserver = _getEventObserver(storyRunner);
+
+  if (eventObserver && eventObserver.isObserving) {
+    return await _waitForEventObserver(eventObserver, {
+      pattern,
+      timeout,
+      invert,
+      player
+    });
+  }
+
+  // Fall back to timeout mode (simple, works without EventObserver)
+  return await _waitForTimeout({ timeout, invert });
+}
+
+/**
+ * Get EventObserver from StoryRunner's backends
+ *
+ * Tries multiple strategies to find an available EventObserver:
+ * 1. Any player backend's EventObserver (MineflayerBackend)
+ * 2. RCON backend's EventObserver (if available)
+ *
+ * @private
+ * @param {Object} storyRunner - StoryRunner instance
+ * @returns {EventObserver|null} EventObserver instance or null
+ */
+function _getEventObserver(storyRunner) {
+  if (!storyRunner || !storyRunner.backends) {
+    return null;
+  }
+
+  // Strategy 1: Check player backends (MineflayerBackend may have EventObserver)
+  if (storyRunner.backends.players) {
+    for (const [username, backend] of storyRunner.backends.players) {
+      if (backend && typeof backend.getEventObserver === 'function') {
+        const observer = backend.getEventObserver();
+        if (observer && observer.isObserving) {
+          return observer;
+        }
+      }
+    }
+  }
+
+  // Strategy 2: Check RCON backend (unlikely to have EventObserver, but future-proof)
+  if (storyRunner.backends.rcon && typeof storyRunner.backends.rcon.getEventObserver === 'function') {
+    const observer = storyRunner.backends.rcon.getEventObserver();
+    if (observer && observer.isObserving) {
+      return observer;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Wait for event using EventObserver (event-driven mode)
+ *
+ * @private
+ * @param {EventObserver} eventObserver - EventObserver instance
+ * @param {Object} options - Options
+ * @returns {Promise<Object|null>} Matching event or null
+ */
+async function _waitForEventObserver(eventObserver, options) {
+  const { pattern, timeout, invert, player } = options;
+
+  return new Promise((resolve) => {
+    let timer = null;
+    let unsubscribe = null;
+
+    const cleanup = (result) => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      if (unsubscribe) {
+        unsubscribe();
+        unsubscribe = null;
+      }
+      resolve(result);
+    };
+
+    // Set timeout
+    timer = setTimeout(() => {
+      cleanup(null);  // Timeout - return null
+    }, timeout);
+
+    // Subscribe to all events
+    unsubscribe = eventObserver.onEvent('*', (event) => {
+      // Filter by player if specified
+      if (player && event.data?.player !== player) {
+        return;
+      }
+
+      // Check if pattern matches
+      const matches = _checkEventMatch(event, pattern);
+
+      if (invert) {
+        // Inverted mode: wait for event that DOESN'T match pattern
+        // For inverted mode, we can't easily detect "absence" of events
+        // So we just wait for timeout and verify no matching events occurred
+        // This is a simplified approach - could be enhanced with event tracking
+        if (!matches) {
+          // Got a non-matching event, but we can't conclude yet
+          // Continue waiting for timeout or matching event
+        } else {
+          // Got a matching event in inverted mode - this is "bad"
+          // We could reject here, but for now we just continue
+          // The caller will interpret null as "no matching events during timeout"
+        }
+      } else {
+        // Normal mode: wait for event that MATCHES pattern
+        if (matches) {
+          cleanup(event);  // Found matching event - return it
+        }
+      }
+    });
+
+    // For inverted mode, we need to track if we saw any matching events
+    // This is a simple implementation - could be enhanced
+    if (invert) {
+      // In inverted mode, we just wait for timeout
+      // The assumption is: no matching events = success
+      // This is not perfect but works for simple cases
+    }
+  });
+}
+
+/**
+ * Wait using simple timeout (fallback mode)
+ *
+ * @private
+ * @param {Object} options - Options
+ * @returns {Promise<null>} Always returns null after timeout
+ */
+async function _waitForTimeout(options) {
+  const { timeout } = options;
+  await new Promise(resolve => setTimeout(resolve, timeout));
+  return null;
+}
+
+/**
+ * Check if event matches the pattern
+ *
+ * Checks multiple fields in the event for pattern matching:
+ * - event.type (e.g., "command.issued", "block.broken")
+ * - event.message (raw log message)
+ * - event.data (additional event data)
+ *
+ * @private
+ * @param {Object} event - Event object from EventObserver
+ * @param {string} pattern - Glob pattern to match
+ * @returns {boolean} True if pattern matches event
+ */
+function _checkEventMatch(event, pattern) {
+  if (!event || !pattern) {
+    return false;
+  }
+
+  // Check event type
+  if (event.type && _matchPattern(event.type, pattern)) {
+    return true;
+  }
+
+  // Check raw message (if available)
+  if (event.message && _matchPattern(event.message, pattern)) {
+    return true;
+  }
+
+  // Check data fields
+  if (event.data) {
+    // Convert data to string for matching
+    const dataStr = JSON.stringify(event.data);
+    if (_matchPattern(dataStr, pattern)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Get default timeout for an action type
+ *
+ * Returns reasonable defaults for different action types:
+ * - Block actions: 3-5 seconds
+ * - Movement: 1-2 seconds
+ * - Entity interaction: 3-5 seconds
+ * - Commands: 2-3 seconds
+ *
+ * @param {string} actionType - Action type (e.g., 'break_block', 'place_block')
+ * @returns {number} Timeout in milliseconds
+ */
+function getDefaultTimeout(actionType) {
+  const timeouts = {
+    // Block interaction (slowest)
+    'break_block': 5000,
+    'place_block': 5000,
+    'interact_with_block': 3000,
+
+    // Movement (fast)
+    'move_forward': 2000,
+    'move_backward': 2000,
+    'move_left': 2000,
+    'move_right': 2000,
+    'jump': 1000,
+    'look_at': 1000,
+    'navigate_to': 15000,  // Pathfinding can be slow
+
+    // Entity interaction (medium)
+    'attack_entity': 3000,
+    'interact_with_entity': 5000,
+    'mount_entity': 3000,
+    'dismount': 1000,
+
+    // Inventory (medium)
+    'drop_item': 2000,
+    'consume_item': 2000,
+    'equip_item': 2000,
+    'swap_inventory_slots': 1000,
+
+    // Commands (fast)
+    'execute_command': 3000,
+    'execute_player_command': 3000,
+    'chat': 2000,
+
+    // Default
+    'default': 5000
+  };
+
+  return timeouts[actionType] || timeouts['default'];
+}
+
+module.exports = {
+  waitForServerConfirmation,
+  _matchPattern,  // Exported for testing
+  getDefaultTimeout
+};

package/lib/helpers/entities.js

@@ -0,0 +1,344 @@
+/**
+ * EntityUtils - Utility functions for working with Mineflayer entities
+ *
+ * Provides helper methods for finding and querying entities in a
+ * Mineflayer bot's entity list.
+ *
+ * Responsibilities (MECE):
+ * - ONLY: Entity lookup and query utilities
+ * - NOT: Entity manipulation (use bot methods directly)
+ * - NOT: Entity spawning/despawning (server-side actions)
+ */
+
+/**
+ * Entity alias mappings
+ * Maps generic entity names to their specific Minecraft entity type names
+ * Used when the summon command accepts a generic name but spawns a specific variant
+ *
+ * @private
+ * @constant {Object<string, string[]>}
+ */
+const ENTITY_ALIASES = {
+  // Generic boat → oak_boat (default boat type in Minecraft)
+  'boat': ['oak_boat', 'boat'],
+  // Generic horse → horse (already correct)
+  // Generic minecart → minecart (already correct)
+};
+
+/**
+ * Get all possible entity names to search for an entity
+ * Includes the original name plus any known aliases/variants
+ *
+ * @private
+ * @param {string} identifier - Entity identifier to search for
+ * @returns {Array<string>} Array of possible entity names to search
+ */
+function _getSearchNames(identifier) {
+  // Always include the original identifier
+  const names = [identifier];
+
+  // Check if this is an alias for a specific entity type
+  if (ENTITY_ALIASES[identifier]) {
+    names.push(...ENTITY_ALIASES[identifier]);
+  }
+
+  // For boats, also try all wood variants if searching for generic "boat"
+  if (identifier === 'boat') {
+    const woodTypes = ['oak', 'birch', 'spruce', 'jungle', 'acacia', 'dark_oak', 'mangrove', 'cherry', 'pale_oak'];
+    woodTypes.forEach(wood => {
+      names.push(`${wood}_boat`);
+    });
+  }
+
+  return [...new Set(names)]; // Remove duplicates
+}
+
+/**
+ * Find an entity by identifier
+ *
+ * Searches for an entity using multiple strategies:
+ * 1. Direct entity ID (number)
+ * 2. Custom name (named entities, mobs with nametags)
+ * 3. Display name (player names, entity display names)
+ * 4. Entity type name (zombie, skeleton, etc.) with alias support
+ *
+ * @param {Object} bot - Mineflayer bot instance
+ * @param {number|string} identifier - Entity ID, name, or custom name
+ * @returns {Object|null} Entity object or null if not found
+ *
+ * @example
+ * // Find by entity ID
+ * const entity = EntityUtils.findEntity(bot, 123);
+ *
+ * @example
+ * // Find by custom name
+ * const entity = EntityUtils.findEntity(bot, 'MyPet');
+ *
+ * @example
+ * // Find by entity type
+ * const entity = EntityUtils.findEntity(bot, 'zombie');
+ *
+ * @example
+ * // Find by alias (boat searches for oak_boat, birch_boat, etc.)
+ * const entity = EntityUtils.findEntity(bot, 'boat');
+ */
+function findEntity(bot, identifier) {
+  if (!bot || !bot.entities) {
+    return null;
+  }
+
+  // Strategy 1: Direct entity ID (number)
+  if (typeof identifier === 'number') {
+    return bot.entities[identifier] || null;
+  }
+
+  const allEntities = Object.values(bot.entities).filter(e => e);
+
+  // Strategy 2: Try custom name (named mobs, nametags)
+  let entity = Object.values(bot.entities).find(e => {
+    if (!e) return false;
+    const customName = e.customName;
+    // Check both string and text component formats
+    if (typeof customName === 'string') {
+      return customName === identifier;
+    }
+    if (customName && typeof customName === 'object' && customName.text) {
+      return customName.text === identifier;
+    }
+    return false;
+  });
+
+  if (entity) {
+    return entity;
+  }
+
+  // Strategy 3: Try display name (players, some entities)
+  entity = Object.values(bot.entities).find(e => {
+    if (!e) return false;
+    return e.displayName === identifier ||
+           (e.username && e.username === identifier);
+  });
+
+  if (entity) {
+    return entity;
+  }
+
+  // Strategy 4: Try entity type name with alias support
+  const searchNames = _getSearchNames(identifier);
+
+  entity = Object.values(bot.entities).find(e => {
+    if (!e) return false;
+    // Check if entity name matches any of the search names
+    return searchNames.includes(e.name) ||
+           (e.type && searchNames.includes(e.type));
+  });
+
+  if (entity) {
+    return entity;
+  }
+
+  return null;
+}
+
+/**
+ * Calculate distance between two positions
+ *
+ * @private
+ * @param {Object} pos1 - First position {x, y, z}
+ * @param {Object} pos2 - Second position {x, y, z}
+ * @returns {number} Distance in blocks
+ */
+function _calculateDistance(pos1, pos2) {
+  if (!pos1 || !pos2) return Infinity;
+  const dx = pos2.x - pos1.x;
+  const dy = pos2.y - pos1.y;
+  const dz = pos2.z - pos1.z;
+  return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+
+/**
+ * Get the nearest entity of a specific type
+ *
+ * @param {Object} bot - Mineflayer bot instance
+ * @param {string} typeName - Entity type name (e.g., 'zombie', 'player')
+ * @param {number} [maxDistance=32] - Maximum search distance in blocks
+ * @returns {Object|null} Nearest entity or null if not found
+ *
+ * @example
+ * // Find nearest zombie within 32 blocks
+ * const zombie = EntityUtils.getNearestEntity(bot, 'zombie', 32);
+ *
+ * @example
+ * // Find nearest player within 16 blocks
+ * const player = EntityUtils.getNearestEntity(bot, 'player', 16);
+ */
+function getNearestEntity(bot, typeName, maxDistance = 32) {
+  if (!bot || !bot.entities || !bot.entity) {
+    return null;
+  }
+
+  const playerPos = bot.entity.position;
+
+  // Find all entities of the specified type within max distance
+  const nearbyEntities = Object.values(bot.entities)
+    .filter(e => {
+      if (!e || !e.position || !e.name) return false;
+      // Match entity type
+      return e.name === typeName;
+    })
+    .map(e => ({
+      entity: e,
+      distance: _calculateDistance(playerPos, e.position)
+    }))
+    .filter(e => e.distance <= maxDistance);
+
+  // Sort by distance (nearest first)
+  nearbyEntities.sort((a, b) => a.distance - b.distance);
+
+  // Return nearest entity or null
+  return nearbyEntities.length > 0 ? nearbyEntities[0].entity : null;
+}
+
+/**
+ * Get all entities of a specific type within distance
+ *
+ * @param {Object} bot - Mineflayer bot instance
+ * @param {string} typeName - Entity type name
+ * @param {number} [maxDistance=32] - Maximum search distance in blocks
+ * @returns {Array<Object>} Array of matching entities (sorted by distance)
+ *
+ * @example
+ * // Get all zombies within 32 blocks
+ * const zombies = EntityUtils.getEntitiesOfType(bot, 'zombie', 32);
+ */
+function getEntitiesOfType(bot, typeName, maxDistance = 32) {
+  if (!bot || !bot.entities || !bot.entity) {
+    return [];
+  }
+
+  const playerPos = bot.entity.position;
+
+  const nearbyEntities = Object.values(bot.entities)
+    .filter(e => {
+      if (!e || !e.position || !e.name) return false;
+      return e.name === typeName && _calculateDistance(playerPos, e.position) <= maxDistance;
+    })
+    .map(e => ({
+      entity: e,
+      distance: _calculateDistance(playerPos, e.position)
+    }))
+    .sort((a, b) => a.distance - b.distance);
+
+  return nearbyEntities.map(e => e.entity);
+}
+
+/**
+ * Find multiple entities by matching a predicate
+ *
+ * @param {Object} bot - Mineflayer bot instance
+ * @param {Function} predicate - Function that returns true for matching entities
+ * @param {number} [maxDistance=32] - Maximum search distance in blocks
+ * @returns {Array<Object>} Array of matching entities (sorted by distance)
+ *
+ * @example
+ * // Find all hostile mobs with low health
+ * const weakHostiles = EntityUtils.findEntities(bot, (e) => {
+ *   return e.health < 10 && isHostile(e.name);
+ * }, 32);
+ */
+function findEntities(bot, predicate, maxDistance = 32) {
+  if (!bot || !bot.entities || !bot.entity || typeof predicate !== 'function') {
+    return [];
+  }
+
+  const playerPos = bot.entity.position;
+
+  const matchingEntities = Object.values(bot.entities)
+    .filter(e => {
+      if (!e || !e.position) return false;
+      return _calculateDistance(playerPos, e.position) <= maxDistance && predicate(e);
+    })
+    .map(e => ({
+      entity: e,
+      distance: _calculateDistance(playerPos, e.position)
+    }))
+    .sort((a, b) => a.distance - b.distance);
+
+  return matchingEntities.map(e => e.entity);
+}
+
+/**
+ * Get distance from player to an entity
+ *
+ * @param {Object} bot - Mineflayer bot instance
+ * @param {Object} entity - Entity object
+ * @returns {number|null} Distance in blocks, or null if invalid
+ */
+function getDistanceToEntity(bot, entity) {
+  if (!bot || !bot.entity || !entity || !entity.position) {
+    return null;
+  }
+
+  return _calculateDistance(bot.entity.position, entity.position);
+}
+
+/**
+ * Check if an entity is alive (has health > 0)
+ *
+ * @param {Object} entity - Entity object
+ * @returns {boolean} True if entity is alive
+ */
+function isEntityAlive(entity) {
+  if (!entity) return false;
+  // Some entities may not have health property
+  return entity.health === undefined || entity.health > 0;
+}
+
+/**
+ * Get entity display name (with fallbacks)
+ *
+ * Returns the most appropriate name for display:
+ * 1. Custom name (nametag)
+ * 2. Username (for players)
+ * 3. Display name
+ * 4. Entity type name
+ *
+ * @param {Object} entity - Entity object
+ * @returns {string} Display name
+ */
+function getEntityDisplayName(entity) {
+  if (!entity) return 'Unknown';
+
+  // Try custom name first
+  if (entity.customName) {
+    if (typeof entity.customName === 'string') {
+      return entity.customName;
+    }
+    if (typeof entity.customName === 'object' && entity.customName.text) {
+      return entity.customName.text;
+    }
+  }
+
+  // Try username (for players)
+  if (entity.username) {
+    return entity.username;
+  }
+
+  // Try display name
+  if (entity.displayName) {
+    return entity.displayName;
+  }
+
+  // Fall back to entity type name
+  return entity.name || 'Unknown';
+}
+
+module.exports = {
+  findEntity,
+  getNearestEntity,
+  getEntitiesOfType,
+  findEntities,
+  getDistanceToEntity,
+  isEntityAlive,
+  getEntityDisplayName
+};

package/lib/index.js

@@ -3,6 +3,8 @@ const { PilafReporter } = require('./reporters/pilaf-reporter');
 const { StoryRunner } = require('./StoryRunner');
 const { waitForEvents, captureEvents } = require('./helpers/events');
 const { captureState, compareStates } = require('./helpers/state');
+const { CorrelationUtils } = require('./helpers/correlation');
+const { EntityUtils } = require('./helpers/entities');
 const { toHaveReceivedLightningStrikes } = require('./matchers/game-matchers');
 const { createTestContext, cleanupTestContext } = require('./test-context');
 
@@ -49,6 +51,8 @@ module.exports = {
   captureEvents,
   captureState,
   compareStates,
+  CorrelationUtils,
+  EntityUtils,
 
   // Matchers
   toHaveReceivedLightningStrikes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilaf/framework",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "main": "lib/index.js",
   "repository": {
     "type": "git",
@@ -20,8 +20,9 @@
   "dependencies": {
     "jest": "^29.7.0",
     "js-yaml": "^4.1.0",
-    "@pilaf/backends": "1.2.2",
-    "@pilaf/reporting": "1.2.2"
+    "mineflayer-pathfinder": "^2.4.5",
+    "@pilaf/backends": "1.3.0",
+    "@pilaf/reporting": "1.3.0"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0"