elsabro 5.2.0 → 6.0.1

package/flow-engine/src/runner.js

@@ -0,0 +1,184 @@
+'use strict';
+
+/**
+ * Main execution loop for the ELSABRO flow engine.
+ *
+ * Traverses the node graph sequentially, dispatching to type-specific
+ * executors, saving checkpoints after each node, and handling
+ * not_implemented nodes gracefully.
+ */
+
+const { getExecutor, checkRuntimeStatus, NotImplementedError } = require('./executors');
+
+class RunnerError extends Error {
+  constructor(message, nodeId) {
+    super(message);
+    this.name = 'RunnerError';
+    this.nodeId = nodeId || null;
+  }
+}
+
+/**
+ * Run a flow from the entry node (or from a checkpoint).
+ *
+ * @param {object} engine – FlowEngine instance (has .graph)
+ * @param {object} inputs – flow inputs (task, profile, complexity, etc.)
+ * @param {object} callbacks – all external action callbacks
+ * @param {object} [checkpoint] – optional checkpoint to resume from
+ * @returns {Promise<{ success: boolean, outputs: object, context: object, nodesVisited: string[] }>}
+ */
+async function runFlow(engine, inputs, callbacks, checkpoint) {
+  const graph = engine.graph;
+  if (!graph) {
+    throw new RunnerError('No flow loaded. Call engine.loadFlow() first.');
+  }
+
+  // Build or restore context
+  const context = checkpoint
+    ? deserializeContext(checkpoint.context)
+    : {
+        inputs: inputs || {},
+        nodes: {},
+        steps: {},
+        state: {},
+        _iterations: {}
+      };
+
+  // If not resuming, set inputs
+  if (!checkpoint) {
+    context.inputs = inputs || {};
+  }
+
+  let currentNodeId = checkpoint ? checkpoint.nextNode : graph.entryNode;
+  const nodesVisited = checkpoint ? (checkpoint.nodesVisited || []) : [];
+  const maxNodes = 200; // Safety: prevent infinite loops
+  let nodeCount = 0;
+
+  while (currentNodeId !== null) {
+    nodeCount++;
+    if (nodeCount > maxNodes) {
+      throw new RunnerError(
+        `Flow exceeded maximum node traversals (${maxNodes}). Possible infinite loop.`,
+        currentNodeId
+      );
+    }
+
+    const node = graph.nodes.get(currentNodeId);
+    if (!node) {
+      throw new RunnerError(`Node "${currentNodeId}" not found in graph`, currentNodeId);
+    }
+
+    // 1. Notify: node starting
+    if (callbacks.onNodeStart) {
+      await callbacks.onNodeStart(node.id, node.type);
+    }
+
+    // 2. Check runtime_status + Execute node
+    const executor = getExecutor(node.type);
+    let result;
+
+    try {
+      checkRuntimeStatus(node);
+      result = await executor(node, context, callbacks);
+    } catch (err) {
+      // Let NotImplementedError propagate cleanly
+      if (err instanceof NotImplementedError) {
+        // Save a checkpoint before stopping
+        if (callbacks.onCheckpoint) {
+          await callbacks.onCheckpoint({
+            currentNode: node.id,
+            nextNode: null,
+            context: serializeContext(context),
+            nodesVisited,
+            stoppedAt: node.id,
+            reason: err.message
+          });
+        }
+        throw err;
+      }
+
+      // Other errors: try onError route if the node has one
+      if (node.onError) {
+        result = { next: node.onError, outputs: { error: err.message } };
+      } else {
+        throw err;
+      }
+    }
+
+    // 4. Store outputs
+    context.nodes[node.id] = context.nodes[node.id] || {};
+    context.nodes[node.id].outputs = result.outputs || {};
+
+    nodesVisited.push(node.id);
+
+    // 5. Checkpoint
+    if (callbacks.onCheckpoint) {
+      await callbacks.onCheckpoint({
+        currentNode: node.id,
+        nextNode: result.next,
+        context: serializeContext(context),
+        nodesVisited: [...nodesVisited]
+      });
+    }
+
+    // 6. Notify: node completed
+    if (callbacks.onNodeComplete) {
+      await callbacks.onNodeComplete(node.id, result);
+    }
+
+    // 7. Advance
+    currentNodeId = result.next;
+  }
+
+  // Determine success based on which exit node was reached
+  const lastNodeId = nodesVisited[nodesVisited.length - 1];
+  const lastNode = graph.nodes.get(lastNodeId);
+  const isSuccess = lastNode && lastNode.status === 'success';
+
+  return {
+    success: isSuccess,
+    outputs: context.nodes[lastNodeId]?.outputs || {},
+    context,
+    nodesVisited
+  };
+}
+
+/**
+ * Create a JSON-serializable copy of context (strips functions, circular refs).
+ *
+ * @param {object} context
+ * @returns {object}
+ */
+function serializeContext(context) {
+  const safe = {};
+
+  for (const key of ['inputs', 'nodes', 'steps', 'state', '_iterations']) {
+    if (context[key] !== undefined) {
+      try {
+        safe[key] = JSON.parse(JSON.stringify(context[key]));
+      } catch {
+        safe[key] = null;
+      }
+    }
+  }
+
+  return safe;
+}
+
+/**
+ * Reconstruct a context from a checkpoint.
+ *
+ * @param {object} data
+ * @returns {object}
+ */
+function deserializeContext(data) {
+  return {
+    inputs: data.inputs || {},
+    nodes: data.nodes || {},
+    steps: data.steps || {},
+    state: data.state || {},
+    _iterations: data._iterations || {}
+  };
+}
+
+module.exports = { runFlow, serializeContext, deserializeContext, RunnerError };

package/flow-engine/src/template.js

@@ -0,0 +1,290 @@
+'use strict';
+
+/**
+ * Template expression resolver for ELSABRO flow engine.
+ *
+ * Handles 7 expression types:
+ * 1. Simple interpolation:  {{inputs.task}}
+ * 2. Deep path access:      {{nodes.X.outputs.Y.Z}}
+ * 3. Fallback operator:     {{expr || defaultValue}}
+ * 4. Boolean expressions:   {{a === 0 && b === 0}}
+ * 5. Function calls:        {{functionName(args)}}
+ * 6. Filter syntax:         {{value | filterName}}
+ * 7. Object/array recursion
+ */
+
+class TemplateError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'TemplateError';
+  }
+}
+
+// Registry for built-in functions and filters
+const _functions = new Map();
+const _filters = new Map();
+
+/**
+ * Register a built-in function that can be called from templates.
+ * @param {string} name
+ * @param {function} fn
+ */
+function registerFunction(name, fn) {
+  _functions.set(name, fn);
+}
+
+/**
+ * Register a filter that can be piped to.
+ * @param {string} name
+ * @param {function} fn
+ */
+function registerFilter(name, fn) {
+  _filters.set(name, fn);
+}
+
+// ---------- Built-in functions ----------
+
+registerFunction('collectOutputs', (context, key) => {
+  const results = [];
+  if (context.nodes) {
+    for (const nodeData of Object.values(context.nodes)) {
+      const outputs = nodeData.outputs || nodeData;
+      if (outputs && outputs[key] !== undefined) {
+        const val = outputs[key];
+        if (Array.isArray(val)) {
+          results.push(...val);
+        } else {
+          results.push(val);
+        }
+      }
+    }
+  }
+  return results;
+});
+
+registerFunction('collectDecisions', (context) => {
+  return (context.state && context.state.decisions) || [];
+});
+
+registerFunction('collectErrors', (context) => {
+  return (context.state && context.state.errors) || [];
+});
+
+registerFunction('hasCriticalIssues', (context, obj) => {
+  if (!obj) return false;
+  const json = typeof obj === 'string' ? obj : JSON.stringify(obj);
+  return json.includes('"critical"') || json.includes('"blocking"');
+});
+
+registerFunction('generateSummary', (context) => {
+  const state = context.state || {};
+  const nodeCount = context.nodes ? Object.keys(context.nodes).length : 0;
+  return `Flow completed. ${nodeCount} nodes executed. Status: ${state.status || 'unknown'}`;
+});
+
+// ---------- Built-in filters ----------
+
+registerFilter('slugify', (value) => {
+  if (typeof value !== 'string') return String(value);
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_]+/g, '-')
+    .replace(/-+/g, '-');
+});
+
+// ---------- Path resolution ----------
+
+/**
+ * Walk a dotted path on an object. Returns undefined if any segment is missing.
+ * @param {object} obj
+ * @param {string} pathStr – e.g. "nodes.skill_discovery.outputs.discoveryResult"
+ * @returns {*}
+ */
+function resolvePath(obj, pathStr) {
+  const parts = pathStr.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+// ---------- Expression parsing ----------
+
+/**
+ * Try to parse a literal value (number, boolean, string, array).
+ * Returns { value, matched } or { matched: false }.
+ */
+function parseLiteral(str) {
+  const trimmed = str.trim();
+
+  // Boolean
+  if (trimmed === 'true') return { value: true, matched: true };
+  if (trimmed === 'false') return { value: false, matched: true };
+
+  // Number
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+    return { value: Number(trimmed), matched: true };
+  }
+
+  // Quoted string (single or double)
+  const strMatch = trimmed.match(/^(['"])(.*)\1$/);
+  if (strMatch) {
+    return { value: strMatch[2], matched: true };
+  }
+
+  // Empty array
+  if (trimmed === '[]') return { value: [], matched: true };
+  if (trimmed === '{}') return { value: {}, matched: true };
+
+  return { matched: false };
+}
+
+/**
+ * Resolve a single expression string (the content inside {{ }}).
+ *
+ * @param {string} expr – raw expression without {{ }}
+ * @param {object} context – { inputs, nodes, steps, state }
+ * @returns {*}
+ */
+function resolveExpression(expr, context) {
+  const trimmed = expr.trim();
+
+  // 1. Check for filter syntax: "value | filterName"
+  //    Only match pipes that are NOT inside || (fallback operator)
+  const filterMatch = trimmed.match(/^(.+?)\s*\|\s*(?!\|)(\w+)\s*$/);
+  if (filterMatch) {
+    const innerValue = resolveExpression(filterMatch[1], context);
+    const filterName = filterMatch[2];
+    const filter = _filters.get(filterName);
+    if (!filter) {
+      throw new TemplateError(`Unknown filter: "${filterName}"`);
+    }
+    return filter(innerValue);
+  }
+
+  // 2. Check for fallback operator: "expr || default"
+  const fallbackMatch = trimmed.match(/^(.+?)\s*\|\|\s*(.+)$/);
+  if (fallbackMatch) {
+    const primary = resolveExpression(fallbackMatch[1], context);
+    if (primary != null && primary !== '') return primary;
+    // Try to resolve the default as an expression or literal
+    const fallbackLiteral = parseLiteral(fallbackMatch[2]);
+    if (fallbackLiteral.matched) return fallbackLiteral.value;
+    return resolveExpression(fallbackMatch[2], context);
+  }
+
+  // 3. Check for negation: "!expr"
+  if (trimmed.startsWith('!')) {
+    const inner = resolveExpression(trimmed.slice(1), context);
+    return !inner;
+  }
+
+  // 4. Check for boolean && expression
+  if (trimmed.includes('&&')) {
+    const parts = trimmed.split('&&').map(p => p.trim());
+    return parts.every(part => {
+      const val = resolveExpression(part, context);
+      return !!val;
+    });
+  }
+
+  // 5. Check for comparison operators: ===, !==
+  const compMatch = trimmed.match(/^(.+?)\s*(===|!==)\s*(.+)$/);
+  if (compMatch) {
+    const left = resolveExpression(compMatch[1], context);
+    const right = resolveExpression(compMatch[3], context);
+    if (compMatch[2] === '===') return left === right;
+    if (compMatch[2] === '!==') return left !== right;
+  }
+
+  // 6. Check for function call: "functionName(args)"
+  const funcMatch = trimmed.match(/^(\w+)\(([^)]*)\)$/);
+  if (funcMatch) {
+    const funcName = funcMatch[1];
+    const fn = _functions.get(funcName);
+    if (!fn) {
+      throw new TemplateError(`Unknown function: "${funcName}"`);
+    }
+    const argsStr = funcMatch[2].trim();
+    if (argsStr === '') {
+      return fn(context);
+    }
+    // Parse argument: could be a path reference or a quoted string
+    const argLiteral = parseLiteral(argsStr);
+    if (argLiteral.matched) {
+      return fn(context, argLiteral.value);
+    }
+    // Resolve as expression (path)
+    const argValue = resolveExpression(argsStr, context);
+    return fn(context, argValue);
+  }
+
+  // 7. Literal value
+  const literal = parseLiteral(trimmed);
+  if (literal.matched) return literal.value;
+
+  // 8. Path resolution (the most common case)
+  const value = resolvePath(context, trimmed);
+  return value;
+}
+
+/**
+ * Resolve all {{expression}} patterns in a template.
+ *
+ * If the template is a string, replace all {{ }} patterns.
+ * If the template is an object or array, recursively resolve all string values.
+ * If the template is not a string/object/array, return as-is.
+ *
+ * @param {*} template
+ * @param {object} context
+ * @returns {*}
+ */
+function resolveTemplate(template, context) {
+  if (template == null) return template;
+
+  if (typeof template === 'string') {
+    // Check if the ENTIRE string is a single expression (return raw value, not stringified)
+    const fullMatch = template.match(/^\{\{(.+)\}\}$/s);
+    if (fullMatch && !template.includes('}}{{')) {
+      return resolveExpression(fullMatch[1], context);
+    }
+
+    // Otherwise, interpolate all {{ }} patterns as strings
+    return template.replace(/\{\{(.+?)\}\}/g, (_, expr) => {
+      const value = resolveExpression(expr, context);
+      if (value === undefined || value === null) return '';
+      if (typeof value === 'object') return JSON.stringify(value);
+      return String(value);
+    });
+  }
+
+  if (Array.isArray(template)) {
+    return template.map(item => resolveTemplate(item, context));
+  }
+
+  if (typeof template === 'object') {
+    const result = {};
+    for (const [key, value] of Object.entries(template)) {
+      result[key] = resolveTemplate(value, context);
+    }
+    return result;
+  }
+
+  return template;
+}
+
+module.exports = {
+  resolveTemplate,
+  resolveExpression,
+  registerFunction,
+  registerFilter,
+  resolvePath,
+  TemplateError,
+  // Expose registries for testing
+  _functions,
+  _filters
+};