@matware/e2e-runner 1.1.1 → 1.3.0

package/src/module-resolver.js

@@ -0,0 +1,310 @@
+/**
+ * Module Resolver for E2E Runner
+ *
+ * Enables reusable action sequences via $use references.
+ * Modules are JSON files in the modules directory with a $module key.
+ *
+ * Features:
+ * - Parameter substitution: {{param}} and {{#param}}...{{/param}} conditionals
+ * - Module composition: modules can $use other modules
+ * - Cycle detection: prevents infinite recursion
+ * - Fail-fast: required params without values throw immediately
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { KNOWN_ACTION_TYPES } from './actions.js';
+
+/**
+ * Loads all module definitions from a directory.
+ * @param {string} modulesDir - Absolute path to modules directory
+ * @returns {Map<string, object>} Map of module name -> definition
+ */
+export function loadModuleRegistry(modulesDir) {
+  const registry = new Map();
+
+  if (!modulesDir || !fs.existsSync(modulesDir)) {
+    return registry;
+  }
+
+  const files = fs.readdirSync(modulesDir).filter(f => f.endsWith('.json'));
+
+  for (const file of files) {
+    const filePath = path.join(modulesDir, file);
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+
+    if (!data.$module) {
+      continue; // Not a module definition
+    }
+
+    if (registry.has(data.$module)) {
+      throw new Error(`Duplicate module name "${data.$module}" in ${file}`);
+    }
+
+    registry.set(data.$module, data);
+  }
+
+  return registry;
+}
+
+/**
+ * Replaces {{param}} placeholders and {{#param}}...{{/param}} conditionals in a string.
+ * @param {string} str - Template string
+ * @param {object} params - Parameter values
+ * @param {object} paramDefs - Parameter definitions from the module (for defaults)
+ * @returns {string} Resolved string
+ */
+function substituteParams(str, params, paramDefs) {
+  if (typeof str !== 'string') return str;
+
+  // Build effective params: defaults + provided
+  const effective = {};
+  if (paramDefs) {
+    for (const [key, def] of Object.entries(paramDefs)) {
+      if (def.default !== undefined) {
+        effective[key] = def.default;
+      }
+    }
+  }
+  Object.assign(effective, params);
+
+  // Process conditional blocks: {{#key}}content{{/key}}
+  let result = str.replace(/\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g, (_, key, content) => {
+    const val = effective[key];
+    if (val !== undefined && val !== '' && val !== null && val !== false) {
+      // Recursively substitute inside the block
+      return substituteParams(content, params, paramDefs);
+    }
+    return '';
+  });
+
+  // Process simple substitutions: {{key}}
+  result = result.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    if (key in effective) return String(effective[key]);
+    return match; // Leave unresolved (will be caught by validation)
+  });
+
+  return result;
+}
+
+/**
+ * Applies parameter substitution to all string fields of an action.
+ * @param {object} action - Action object
+ * @param {object} params - Parameter values
+ * @param {object} paramDefs - Parameter definitions
+ * @returns {object} New action with substituted values
+ */
+function substituteActionParams(action, params, paramDefs, moduleName) {
+  const result = {};
+  for (const [key, value] of Object.entries(action)) {
+    if (typeof value === 'string') {
+      result[key] = substituteParams(value, params, paramDefs);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  // Check for unresolved placeholders
+  for (const [key, value] of Object.entries(result)) {
+    if (typeof value === 'string') {
+      const unresolved = value.match(/\{\{(\w+)\}\}/g);
+      if (unresolved) {
+        const paramNames = unresolved.map(m => m.slice(2, -2));
+        throw new Error(`Module "${moduleName || 'unknown'}": unresolved parameter(s) ${paramNames.join(', ')} in "${key}". Provide them via params or define defaults.`);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Validates that all required parameters have values.
+ * @param {object} paramDefs - Parameter definitions from module
+ * @param {object} params - Provided parameter values
+ * @param {string} moduleName - Module name for error messages
+ */
+function validateParams(paramDefs, params, moduleName) {
+  if (!paramDefs) return;
+
+  for (const [key, def] of Object.entries(paramDefs)) {
+    if (def.required && !(key in params) && def.default === undefined) {
+      throw new Error(`Module "${moduleName}": missing required parameter "${key}"`);
+    }
+  }
+}
+
+/**
+ * Resolves an array of actions, expanding $use references recursively.
+ * @param {Array} actions - Array of actions (may contain $use references)
+ * @param {Map} registry - Module registry
+ * @param {object} contextParams - Parameters from parent scope
+ * @param {Set} visited - Set of module names in the current resolution chain (cycle detection)
+ * @returns {Array} Flattened array of concrete actions
+ */
+function resolveActions(actions, registry, contextParams = {}, visited = new Set()) {
+  const resolved = [];
+
+  for (const action of actions) {
+    if (action.$use) {
+      const moduleName = action.$use;
+
+      // Cycle detection
+      if (visited.has(moduleName)) {
+        throw new Error(`Circular module dependency detected: ${[...visited, moduleName].join(' -> ')}`);
+      }
+
+      const moduleDef = registry.get(moduleName);
+      if (!moduleDef) {
+        throw new Error(`Module not found: "${moduleName}". Available: ${[...registry.keys()].join(', ') || 'none'}`);
+      }
+
+      // Merge params: context params as fallback, then explicit params
+      const mergedParams = { ...contextParams, ...action.params };
+      validateParams(moduleDef.params, mergedParams, moduleName);
+
+      // Recursively resolve the module's actions
+      const newVisited = new Set(visited);
+      newVisited.add(moduleName);
+
+      const moduleActions = moduleDef.actions || [];
+      const substituted = moduleActions.map(a => {
+        if (a.$use) {
+          // Nested $use — pass through for recursive resolution
+          return { ...a, params: { ...mergedParams, ...a.params } };
+        }
+        return substituteActionParams(a, mergedParams, moduleDef.params, moduleName);
+      });
+
+      const expandedActions = resolveActions(substituted, registry, mergedParams, newVisited);
+      resolved.push(...expandedActions);
+    } else {
+      resolved.push(action);
+    }
+  }
+
+  return resolved;
+}
+
+/**
+ * Resolves all $use references in a test data structure.
+ * @param {object} data - { tests, hooks } as returned by normalizeTestData
+ * @param {string} modulesDir - Absolute path to modules directory
+ * @returns {object} New { tests, hooks } with all $use expanded
+ */
+export function resolveTestData(data, modulesDir) {
+  if (!modulesDir || !fs.existsSync(modulesDir)) {
+    return data; // No modules directory — pass through unchanged
+  }
+
+  const registry = loadModuleRegistry(modulesDir);
+  if (registry.size === 0) {
+    return data; // No modules defined — pass through
+  }
+
+  // Check if there are any $use references to resolve
+  const hasUseRef = (actions) => actions?.some(a => a.$use);
+  const hooksNeedResolving = Object.values(data.hooks || {}).some(hasUseRef);
+  const testsNeedResolving = data.tests?.some(t => hasUseRef(t.actions));
+
+  if (!hooksNeedResolving && !testsNeedResolving) {
+    return data; // No $use references — pass through
+  }
+
+  // Resolve hooks
+  const resolvedHooks = {};
+  for (const [hookName, actions] of Object.entries(data.hooks || {})) {
+    if (Array.isArray(actions)) {
+      resolvedHooks[hookName] = resolveActions(actions, registry);
+    } else {
+      resolvedHooks[hookName] = actions;
+    }
+  }
+
+  // Resolve test actions
+  const resolvedTests = (data.tests || []).map(test => {
+    if (!hasUseRef(test.actions)) return test;
+    return {
+      ...test,
+      actions: resolveActions(test.actions, registry),
+    };
+  });
+
+  return { tests: resolvedTests, hooks: resolvedHooks };
+}
+
+/**
+ * Lists available modules with their metadata.
+ * @param {string} modulesDir - Absolute path to modules directory
+ * @returns {Array<{name, description, params, file}>} Module metadata
+ */
+export function listModules(modulesDir) {
+  if (!modulesDir || !fs.existsSync(modulesDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(modulesDir).filter(f => f.endsWith('.json'));
+  const modules = [];
+
+  for (const file of files) {
+    const filePath = path.join(modulesDir, file);
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+
+    if (!data.$module) continue;
+
+    const paramList = data.params
+      ? Object.entries(data.params).map(([name, def]) => ({
+          name,
+          required: !!def.required,
+          default: def.default,
+          description: def.description,
+        }))
+      : [];
+
+    modules.push({
+      name: data.$module,
+      description: data.description || '',
+      file,
+      actionCount: (data.actions || []).length,
+      params: paramList,
+    });
+  }
+
+  return modules;
+}
+
+/**
+ * Validates that all action types in a resolved test data structure are known.
+ * Call AFTER module resolution so $use references have been expanded.
+ * @param {object} data - { tests, hooks } with resolved actions
+ * @param {string} context - File/suite name for error messages
+ * @throws {Error} if any unknown action types are found
+ */
+export function validateActionTypes(data, context) {
+  const unknown = [];
+
+  const check = (actions, location) => {
+    if (!Array.isArray(actions)) return;
+    for (const action of actions) {
+      if (action.$use) continue; // unresolved module ref — skip (shouldn't happen post-resolution)
+      if (action.type && !KNOWN_ACTION_TYPES.has(action.type)) {
+        unknown.push({ type: action.type, location });
+      }
+    }
+  };
+
+  // Check hooks
+  for (const [hookName, actions] of Object.entries(data.hooks || {})) {
+    check(actions, `hooks.${hookName}`);
+  }
+
+  // Check test actions
+  for (const test of data.tests || []) {
+    check(test.actions, `test "${test.name}"`);
+  }
+
+  if (unknown.length > 0) {
+    const details = unknown.map(u => `"${u.type}" in ${u.location}`).join(', ');
+    throw new Error(`Unknown action type(s) in ${context}: ${details}`);
+  }
+}

package/src/narrate.js

@@ -0,0 +1,262 @@
+/**
+ * Action Narrator
+ *
+ * Converts raw action + result data into human-readable narrative strings.
+ * Each test step becomes a sentence describing what happened.
+ */
+
+/**
+ * Generates a human-readable narrative for a single action result.
+ *
+ * @param {object} action  — The original action (type, selector, value, text)
+ * @param {object} result  — The action result (success, duration, error, result)
+ * @returns {string} A narrative string describing what happened
+ */
+export function narrateAction(action, result) {
+  const { type, selector, value, text } = action;
+  const { success, duration, error } = result;
+  const time = duration != null ? ` (${duration}ms)` : '';
+
+  if (!success) {
+    return `FAIL: ${describeIntent(action)} — ${error}`;
+  }
+
+  switch (type) {
+    case 'goto':
+      return `Navigated to ${value}${time}`;
+
+    case 'click':
+      if (selector) return `Clicked on "${selector}"${time}`;
+      if (text) return `Clicked on element with text "${text}"${time}`;
+      return `Clicked${time}`;
+
+    case 'type':
+    case 'fill': {
+      const masked = isSensitive(selector) ? '***' : value;
+      return `Typed "${masked}" into "${selector}"${time}`;
+    }
+
+    case 'wait':
+      if (selector) return `Waited for "${selector}" to appear${time}`;
+      if (text) return `Waited for text "${text}" to appear${time}`;
+      return `Waited ${value}ms`;
+
+    case 'screenshot':
+      if (result.result?.screenshot) {
+        return `Captured screenshot: ${result.result.screenshot}`;
+      }
+      return `Captured screenshot${value ? `: ${value}` : ''}`;
+
+    case 'assert_text':
+      return `Verified text "${text}" is present on page${time}`;
+
+    case 'assert_url':
+      return `Verified URL contains "${value}"${time}`;
+
+    case 'assert_visible':
+      return `Verified "${selector}" is visible${time}`;
+
+    case 'assert_count':
+      return `Verified "${selector}" has ${value} element(s)${time}`;
+
+    case 'assert_element_text':
+      return `Verified "${selector}" contains text "${text}"${time}`;
+
+    case 'assert_attribute':
+      return `Verified attribute on "${selector}": ${value}${time}`;
+
+    case 'assert_class':
+      return `Verified "${selector}" has class "${value}"${time}`;
+
+    case 'assert_not_visible':
+      return `Verified "${selector}" is not visible${time}`;
+
+    case 'assert_input_value':
+      return `Verified input "${selector}" has value "${value}"${time}`;
+
+    case 'assert_matches':
+      return `Verified "${selector}" matches pattern /${value}/${time}`;
+
+    case 'get_text': {
+      const extractedText = result.result?.value;
+      if (extractedText) {
+        const shortText = extractedText.length > 50 ? extractedText.slice(0, 47) + '...' : extractedText;
+        return `Read text from "${selector}": "${shortText}"${time}`;
+      }
+      return `Read text from "${selector}"${time}`;
+    }
+
+    case 'assert_no_network_errors':
+      return `Verified no network errors occurred${time}`;
+
+    case 'select':
+      return `Selected option "${value}" in "${selector}"${time}`;
+
+    case 'clear':
+      return `Cleared input "${selector}"${time}`;
+
+    case 'press':
+      return `Pressed key "${value}"${time}`;
+
+    case 'scroll':
+      if (selector) return `Scrolled to "${selector}"${time}`;
+      return `Scrolled down ${value || 300}px${time}`;
+
+    case 'hover':
+      return `Hovered over "${selector}"${time}`;
+
+    case 'clear_cookies':
+      return `Cleared cookies and storage${value ? ` for ${value}` : ''}${time}`;
+
+    case 'navigate':
+      return `Navigated (SPA) to ${value}${time}`;
+
+    case 'type_react': {
+      const masked = isSensitive(selector) ? '***' : value;
+      return `Typed "${masked}" into React input "${selector}"${time}`;
+    }
+
+    case 'click_regex':
+      if (selector) return `Clicked ${value === 'last' ? 'last ' : ''}element matching /${text}/i in "${selector}"${time}`;
+      return `Clicked ${value === 'last' ? 'last ' : ''}element matching /${text}/i${time}`;
+
+    case 'click_option':
+      return `Clicked dropdown option "${text}"${time}`;
+
+    case 'focus_autocomplete':
+      return `Focused autocomplete labeled "${text}"${time}`;
+
+    case 'click_chip':
+      return `Clicked chip "${text}"${time}`;
+
+    case 'set_storage': {
+      const storageType = selector === 'session' ? 'sessionStorage' : 'localStorage';
+      const eqIdx = value.indexOf('=');
+      const sKey = eqIdx === -1 ? value : value.slice(0, eqIdx);
+      const sVal = eqIdx === -1 ? '' : value.slice(eqIdx + 1);
+      const displayVal = isSensitive(sKey) ? '***' : (sVal.length > 30 ? sVal.slice(0, 27) + '...' : sVal);
+      return `Set ${storageType}.${sKey} = "${displayVal}"${time}`;
+    }
+
+    case 'assert_storage': {
+      const storageType = selector === 'session' ? 'sessionStorage' : 'localStorage';
+      const eqIdx = value.indexOf('=');
+      if (eqIdx === -1) {
+        return `Verified ${storageType} key "${value}" exists${time}`;
+      }
+      return `Verified ${storageType} key "${value.slice(0, eqIdx)}" has expected value${time}`;
+    }
+
+    case 'click_icon':
+      return `Clicked icon "${value}"${selector ? ` in "${selector}"` : ''}${time}`;
+
+    case 'click_menu_item':
+      return `Clicked menu item "${text}"${selector ? ` in "${selector}"` : ''}${time}`;
+
+    case 'click_in_context':
+      return `Clicked "${selector}" in container with text "${text}"${time}`;
+
+    case 'evaluate': {
+      const snippet = value.length > 80 ? value.slice(0, 77) + '...' : value;
+      const evalResult = result.result?.value;
+      if (evalResult !== undefined && evalResult !== null) {
+        const valStr = typeof evalResult === 'string' ? evalResult : JSON.stringify(evalResult);
+        const shortVal = valStr.length > 50 ? valStr.slice(0, 47) + '...' : valStr;
+        return `Executed JS: ${snippet} → ${shortVal}${time}`;
+      }
+      return `Executed JS: ${snippet}${time}`;
+    }
+
+    default:
+      return `Unknown action "${type}"${time}`;
+  }
+}
+
+/**
+ * Describes the intent of an action (used in failure messages).
+ */
+function describeIntent(action) {
+  const { type, selector, value, text } = action;
+
+  switch (type) {
+    case 'goto':       return `Navigate to ${value}`;
+    case 'click':      return selector ? `Click on "${selector}"` : `Click on text "${text}"`;
+    case 'type':
+    case 'fill':       return `Type into "${selector}"`;
+    case 'wait':
+      if (selector)    return `Wait for "${selector}"`;
+      if (text)        return `Wait for text "${text}"`;
+      return           `Wait ${value}ms`;
+    case 'screenshot': return 'Capture screenshot';
+    case 'assert_text':           return `Assert text "${text}" present`;
+    case 'assert_url':            return `Assert URL contains "${value}"`;
+    case 'assert_visible':        return `Assert "${selector}" visible`;
+    case 'assert_count':          return `Assert "${selector}" count = ${value}`;
+    case 'assert_element_text':   return `Assert "${selector}" contains "${text}"`;
+    case 'assert_attribute':      return `Assert attribute on "${selector}": ${value}`;
+    case 'assert_class':          return `Assert "${selector}" has class "${value}"`;
+    case 'assert_not_visible':    return `Assert "${selector}" not visible`;
+    case 'assert_input_value':    return `Assert input "${selector}" value "${value}"`;
+    case 'assert_matches':        return `Assert "${selector}" matches /${value}/`;
+    case 'get_text':              return `Get text from "${selector}"`;
+    case 'assert_no_network_errors': return 'Assert no network errors';
+    case 'select':     return `Select "${value}" in "${selector}"`;
+    case 'clear':      return `Clear "${selector}"`;
+    case 'press':      return `Press key "${value}"`;
+    case 'scroll':     return selector ? `Scroll to "${selector}"` : `Scroll down`;
+    case 'hover':      return `Hover over "${selector}"`;
+    case 'clear_cookies': return 'Clear cookies and storage';
+    case 'navigate':   return `Navigate to ${value}`;
+    case 'type_react':            return `Type into React input "${selector}"`;
+    case 'click_regex':           return `Click element matching /${text}/i`;
+    case 'click_option':          return `Click option "${text}"`;
+    case 'focus_autocomplete':    return `Focus autocomplete "${text}"`;
+    case 'click_chip':            return `Click chip "${text}"`;
+    case 'set_storage':            return `Set ${selector === 'session' ? 'sessionStorage' : 'localStorage'} key "${value?.split('=')[0] || value}"`;
+    case 'assert_storage': {
+      const eqIdx = value?.indexOf('=') ?? -1;
+      return eqIdx === -1
+        ? `Assert ${selector === 'session' ? 'sessionStorage' : 'localStorage'} key "${value}" exists`
+        : `Assert ${selector === 'session' ? 'sessionStorage' : 'localStorage'} key "${value.slice(0, eqIdx)}" value`;
+    }
+    case 'click_icon':             return `Click icon "${value}"`;
+    case 'click_menu_item':        return `Click menu item "${text}"`;
+    case 'click_in_context':       return `Click "${selector}" in context of "${text}"`;
+    case 'evaluate':   return 'Execute JS';
+    default:           return `Action "${type}"`;
+  }
+}
+
+/**
+ * Checks if a selector likely refers to a sensitive field (password, token, etc.)
+ */
+function isSensitive(selector) {
+  if (!selector) return false;
+  return /password|secret|token|pin|ssn|cvv/i.test(selector);
+}
+
+/**
+ * Builds a full test narrative from the result's actions array.
+ * Returns a numbered step-by-step summary.
+ *
+ * @param {object} testResult — A single test result with actions[], name, success, error
+ * @returns {string[]} Array of narrative lines
+ */
+export function narrateTest(testResult) {
+  const lines = [];
+
+  for (let i = 0; i < testResult.actions.length; i++) {
+    const action = testResult.actions[i];
+    const narrative = action.narrative || narrateAction(action, action);
+    lines.push(`${i + 1}. ${narrative}`);
+  }
+
+  if (!testResult.success && testResult.error) {
+    const failedAt = testResult.actions.findIndex(a => !a.success);
+    if (failedAt === -1) {
+      lines.push(`✗ Test failed: ${testResult.error}`);
+    }
+  }
+
+  return lines;
+}

package/src/neo4j-pool.js

@@ -0,0 +1,124 @@
+/**
+ * Neo4j Docker container lifecycle management.
+ *
+ * Follows the same pattern as src/pool.js for Chrome pool management.
+ * Uses docker compose to spin up/stop a Neo4j container.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { log, colors as C } from './logger.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEMPLATE_PATH = path.join(__dirname, '..', 'templates', 'docker-compose-neo4j.yml');
+const NEO4J_DIR = '.e2e-neo4j';
+
+function getComposeDir(cwd) {
+  return path.join(cwd, NEO4J_DIR);
+}
+
+function getComposePath(cwd) {
+  return path.join(getComposeDir(cwd), 'docker-compose.yml');
+}
+
+function ensureComposeFile(config, cwd) {
+  const composeDir = getComposeDir(cwd);
+  const composePath = getComposePath(cwd);
+
+  if (!fs.existsSync(composeDir)) {
+    fs.mkdirSync(composeDir, { recursive: true });
+  }
+
+  const template = fs.readFileSync(TEMPLATE_PATH, 'utf-8');
+  const content = template
+    .replace(/\$\{BOLT_PORT\}/g, String(config.neo4jBoltPort || 7687))
+    .replace(/\$\{HTTP_PORT\}/g, String(config.neo4jHttpPort || 7474))
+    .replace(/\$\{NEO4J_PASSWORD\}/g, config.neo4jPassword || 'e2erunner');
+
+  fs.writeFileSync(composePath, content);
+  return composePath;
+}
+
+/** Start the Neo4j container. */
+export function startNeo4j(config, cwd = null) {
+  cwd = cwd || config._cwd || process.cwd();
+  const composePath = ensureComposeFile(config, cwd);
+  const composeDir = getComposeDir(cwd);
+
+  log('🗄️', `Starting Neo4j on bolt://localhost:${config.neo4jBoltPort || 7687}...`);
+
+  try {
+    execFileSync('docker', ['compose', '-f', composePath, 'up', '-d'], {
+      cwd: composeDir,
+      stdio: 'inherit',
+    });
+    log('✅', `Neo4j started. Browser: ${C.cyan}http://localhost:${config.neo4jHttpPort || 7474}${C.reset}`);
+  } catch (err) {
+    log('❌', `Failed to start Neo4j: ${err.message}`);
+    throw err;
+  }
+}
+
+/** Stop the Neo4j container. */
+export function stopNeo4j(config, cwd = null) {
+  cwd = cwd || config._cwd || process.cwd();
+  const composePath = getComposePath(cwd);
+
+  if (!fs.existsSync(composePath)) {
+    log('⚠️', 'No Neo4j compose file found. Is Neo4j running?');
+    return;
+  }
+
+  log('🗄️', 'Stopping Neo4j...');
+  try {
+    execFileSync('docker', ['compose', '-f', composePath, 'down'], {
+      cwd: getComposeDir(cwd),
+      stdio: 'inherit',
+    });
+    log('✅', 'Neo4j stopped');
+  } catch (err) {
+    log('❌', `Failed to stop Neo4j: ${err.message}`);
+    throw err;
+  }
+}
+
+/** Get Neo4j container status. */
+export function getNeo4jStatus(config, cwd = null) {
+  cwd = cwd || config._cwd || process.cwd();
+  // Ensure compose file exists from template (same as start does)
+  const composePath = ensureComposeFile(config, cwd);
+
+  try {
+    const output = execFileSync('docker', ['compose', '-f', composePath, 'ps', '--format', 'json'], {
+      cwd: getComposeDir(cwd),
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    // docker compose ps --format json outputs one JSON object per line
+    const lines = output.trim().split('\n').filter(Boolean);
+    const containers = lines.map(line => {
+      try { return JSON.parse(line); } catch { return null; }
+    }).filter(Boolean);
+
+    const neo4jContainer = containers.find(c => c.Service === 'neo4j' || c.Name?.includes('neo4j'));
+
+    if (neo4jContainer) {
+      const isRunning = neo4jContainer.State === 'running';
+      return {
+        running: isRunning,
+        state: neo4jContainer.State,
+        boltPort: config.neo4jBoltPort || 7687,
+        httpPort: config.neo4jHttpPort || 7474,
+        boltUrl: config.neo4jBoltUrl || `bolt://localhost:${config.neo4jBoltPort || 7687}`,
+      };
+    }
+
+    return { running: false, error: 'Container not found' };
+  } catch {
+    return { running: false, error: 'Docker compose not available or container not running' };
+  }
+}