@zibby/core 0.1.0

package/src/utils/node-schema-parser.js

@@ -0,0 +1,522 @@
+/**
+ * Node Schema Parser
+ * Extracts exact return schema from node execute functions using AST analysis
+ * Provides 100% accurate state variable information for the Variable Inspector
+ */
+
+import * as acorn from 'acorn';
+import * as walk from 'acorn-walk';
+
+/**
+ * Parse a node definition and extract its state output schema
+ * @param {Object} nodeDefinition - Node definition object with execute function
+ * @returns {Object} Schema describing the node's state output
+ */
+export function parseNodeSchema(nodeDefinition) {
+  if (!nodeDefinition || typeof nodeDefinition.execute !== 'function') {
+    return createUnknownSchema('No execute function found');
+  }
+
+  const code = nodeDefinition.execute.toString();
+  return parseExecuteSchema(code);
+}
+
+/**
+ * Parse execute function code and extract return schema
+ * @param {string} code - Execute function source code
+ * @returns {Object} Schema describing the return value
+ */
+export function parseExecuteSchema(code) {
+  if (!code || typeof code !== 'string') {
+    return createUnknownSchema('Invalid code');
+  }
+
+  try {
+    // Handle different function syntaxes:
+    // 1. async (state) => { ... }
+    // 2. async function(state) { ... }
+    // 3. async execute(state) { ... } (method syntax)
+    let wrappedCode;
+    const trimmed = code.trimStart();
+    
+    if (trimmed.startsWith('async execute(')) {
+      // async execute(state) { ... } -> async (state) => { ... }
+      wrappedCode = `const __fn = async ${trimmed.substring('async execute'.length).replace(/^\(/, '(').replace(/\)\s*\{/, ') => {')}`;
+    } else if (trimmed.startsWith('execute(')) {
+      // execute(state) { ... } -> (state) => { ... }
+      wrappedCode = `const __fn = ${trimmed.substring('execute'.length).replace(/\)\s*\{/, ') => {')}`;
+    } else {
+      wrappedCode = `const __fn = ${trimmed}`;
+    }
+
+    const ast = acorn.parse(wrappedCode, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      allowAwaitOutsideModules: true
+    });
+
+    const returnSchemas = [];
+    const variableScopes = new Map();
+
+    // First pass: collect variable declarations
+    walk.simple(ast, {
+      VariableDeclarator(node) {
+        if (node.id.type === 'Identifier' && node.init) {
+          variableScopes.set(node.id.name, node.init);
+        }
+      }
+    });
+
+    // Second pass: extract return statements
+    walk.simple(ast, {
+      ReturnStatement(node) {
+        if (node.argument) {
+          const schema = extractSchemaFromNode(node.argument, variableScopes);
+          returnSchemas.push(schema);
+        }
+      }
+    });
+
+    if (returnSchemas.length === 0) {
+      return createUnknownSchema('No return statements found');
+    }
+
+    // Merge all return schemas (handles multiple return paths)
+    return mergeSchemas(returnSchemas);
+  } catch (error) {
+    return createUnknownSchema(`Parse error: ${error.message}`);
+  }
+}
+
+/**
+ * Extract schema from an AST node
+ * @param {Object} node - AST node
+ * @param {Map} variableScopes - Map of variable names to their init nodes
+ * @returns {Object} Schema object
+ */
+function extractSchemaFromNode(node, variableScopes) {
+  switch (node.type) {
+    case 'ObjectExpression':
+      return extractObjectSchema(node, variableScopes);
+
+    case 'ArrayExpression':
+      return extractArraySchema(node, variableScopes);
+
+    case 'Literal':
+      return extractLiteralSchema(node);
+
+    case 'Identifier':
+      return resolveIdentifier(node.name, variableScopes);
+
+    case 'MemberExpression':
+      return extractMemberSchema(node);
+
+    case 'ConditionalExpression': {
+      // condition ? consequent : alternate
+      const consequent = extractSchemaFromNode(node.consequent, variableScopes);
+      const alternate = extractSchemaFromNode(node.alternate, variableScopes);
+      return mergeSchemas([consequent, alternate]);
+    }
+
+    case 'LogicalExpression':
+      // a || b, a && b
+      if (node.operator === '||') {
+        return extractSchemaFromNode(node.left, variableScopes);
+      }
+      return extractSchemaFromNode(node.right, variableScopes);
+
+    case 'CallExpression':
+      return extractCallSchema(node);
+
+    case 'AwaitExpression':
+      return extractSchemaFromNode(node.argument, variableScopes);
+
+    case 'TemplateLiteral':
+      return { type: 'string' };
+
+    case 'UnaryExpression':
+      if (node.operator === '!') return { type: 'boolean' };
+      return { type: 'unknown' };
+
+    case 'BinaryExpression':
+      if (['===', '!==', '==', '!=', '<', '>', '<=', '>='].includes(node.operator)) {
+        return { type: 'boolean' };
+      }
+      if (['+', '-', '*', '/', '%'].includes(node.operator)) {
+        return { type: 'number' };
+      }
+      return { type: 'unknown' };
+
+    default:
+      return { type: 'unknown', astType: node.type };
+  }
+}
+
+/**
+ * Extract schema from an object expression
+ */
+function extractObjectSchema(node, variableScopes) {
+  const properties = {};
+
+  for (const prop of node.properties) {
+    if (prop.type === 'SpreadElement') {
+      // Handle spread: { ...variable } or { ...(condition && { prop }) }
+      const spreadSchema = extractSpreadSchema(prop.argument, variableScopes);
+      if (spreadSchema.properties) {
+        for (const [key, value] of Object.entries(spreadSchema.properties)) {
+          properties[key] = { ...value, optional: true };
+        }
+      }
+    } else if (prop.type === 'Property') {
+      const key = getPropertyKey(prop);
+      if (key) {
+        const valueSchema = extractSchemaFromNode(prop.value, variableScopes);
+        properties[key] = valueSchema;
+      }
+    }
+  }
+
+  return {
+    type: 'object',
+    properties
+  };
+}
+
+/**
+ * Extract schema from spread expressions
+ */
+function extractSpreadSchema(node, variableScopes) {
+  // Handle: ...(condition && { prop: value })
+  if (node.type === 'LogicalExpression' && node.operator === '&&') {
+    return extractSchemaFromNode(node.right, variableScopes);
+  }
+
+  // Handle: ...variable
+  if (node.type === 'Identifier') {
+    return resolveIdentifier(node.name, variableScopes);
+  }
+
+  // Handle: ...obj.property
+  if (node.type === 'MemberExpression') {
+    return extractMemberSchema(node);
+  }
+
+  return extractSchemaFromNode(node, variableScopes);
+}
+
+/**
+ * Extract schema from array expression
+ */
+function extractArraySchema(node, variableScopes) {
+  if (node.elements.length === 0) {
+    return { type: 'array', items: { type: 'unknown' } };
+  }
+
+  // Infer item type from first element
+  const firstElement = node.elements[0];
+  if (firstElement) {
+    const itemSchema = extractSchemaFromNode(firstElement, variableScopes);
+    return { type: 'array', items: itemSchema };
+  }
+
+  return { type: 'array', items: { type: 'unknown' } };
+}
+
+/**
+ * Extract schema from literal values
+ */
+function extractLiteralSchema(node) {
+  const value = node.value;
+
+  if (value === null) return { type: 'null' };
+  if (typeof value === 'boolean') return { type: 'boolean', value };
+  if (typeof value === 'number') return { type: 'number' };
+  if (typeof value === 'string') return { type: 'string' };
+
+  return { type: 'unknown' };
+}
+
+/**
+ * Resolve an identifier to its schema
+ */
+function resolveIdentifier(name, variableScopes) {
+  // Check if we have the variable's init expression
+  const initNode = variableScopes.get(name);
+  if (initNode) {
+    return extractSchemaFromNode(initNode, variableScopes);
+  }
+
+  // Common known identifiers
+  const knownTypes = {
+    'true': { type: 'boolean', value: true },
+    'false': { type: 'boolean', value: false },
+    'null': { type: 'null' },
+    'undefined': { type: 'undefined' }
+  };
+
+  if (knownTypes[name]) {
+    return knownTypes[name];
+  }
+
+  // Return reference type with the variable name for context
+  return { type: 'reference', name, label: camelToTitle(name) };
+}
+
+/**
+ * Extract schema from member expression (e.g., obj.prop)
+ */
+function extractMemberSchema(node) {
+  const path = getMemberPath(node);
+  const lastPart = path[path.length - 1];
+
+  // Infer type from common property names
+  const typeHints = {
+    'length': { type: 'number' },
+    'trim': { type: 'string' },
+    'toString': { type: 'string' },
+    'toISOString': { type: 'string' },
+    'success': { type: 'boolean' },
+    'error': { type: 'string' },
+    'message': { type: 'string' },
+    'url': { type: 'string' },
+    'path': { type: 'string' },
+    'name': { type: 'string' },
+    'id': { type: 'string' },
+    'count': { type: 'number' },
+    'total': { type: 'number' },
+    'timestamp': { type: 'string' }
+  };
+
+  return typeHints[lastPart] || {
+    type: 'reference',
+    path: path.join('.'),
+    label: camelToTitle(lastPart)
+  };
+}
+
+/**
+ * Get the full path of a member expression
+ */
+function getMemberPath(node) {
+  const parts = [];
+
+  function traverse(n) {
+    if (n.type === 'MemberExpression') {
+      traverse(n.object);
+      if (n.property.type === 'Identifier') {
+        parts.push(n.property.name);
+      } else if (n.property.type === 'Literal') {
+        parts.push(String(n.property.value));
+      }
+    } else if (n.type === 'Identifier') {
+      parts.push(n.name);
+    }
+  }
+
+  traverse(node);
+  return parts;
+}
+
+/**
+ * Extract schema from call expressions
+ */
+function extractCallSchema(node) {
+  const callee = node.callee;
+
+  // Handle common method calls
+  if (callee.type === 'MemberExpression') {
+    const method = callee.property?.name;
+
+    const methodTypes = {
+      'trim': { type: 'string' },
+      'toString': { type: 'string' },
+      'toISOString': { type: 'string' },
+      'toJSON': { type: 'object' },
+      'join': { type: 'string' },
+      'map': { type: 'array' },
+      'filter': { type: 'array' },
+      'slice': { type: 'array' },
+      'concat': { type: 'array' },
+      'split': { type: 'array' },
+      'stringify': { type: 'string' },
+      'parse': { type: 'object' }
+    };
+
+    if (methodTypes[method]) {
+      return methodTypes[method];
+    }
+  }
+
+  // Handle constructor calls
+  if (callee.type === 'Identifier') {
+    const constructorTypes = {
+      'Date': { type: 'object', label: 'Date' },
+      'Array': { type: 'array' },
+      'Object': { type: 'object' },
+      'String': { type: 'string' },
+      'Number': { type: 'number' },
+      'Boolean': { type: 'boolean' }
+    };
+
+    if (constructorTypes[callee.name]) {
+      return constructorTypes[callee.name];
+    }
+  }
+
+  return { type: 'unknown', call: true };
+}
+
+/**
+ * Get property key from a Property node
+ */
+function getPropertyKey(prop) {
+  if (prop.key.type === 'Identifier') {
+    return prop.key.name;
+  }
+  if (prop.key.type === 'Literal') {
+    return String(prop.key.value);
+  }
+  return null;
+}
+
+/**
+ * Merge multiple schemas (for multiple return paths)
+ */
+function mergeSchemas(schemas) {
+  if (schemas.length === 0) {
+    return createUnknownSchema('Empty schemas');
+  }
+
+  if (schemas.length === 1) {
+    return schemas[0];
+  }
+
+  // If all schemas are objects, merge their properties
+  const objectSchemas = schemas.filter(s => s.type === 'object');
+  if (objectSchemas.length === schemas.length) {
+    const mergedProperties = {};
+
+    for (const schema of objectSchemas) {
+      if (schema.properties) {
+        for (const [key, value] of Object.entries(schema.properties)) {
+          if (mergedProperties[key]) {
+            // Property exists in multiple returns - mark as potentially optional
+            mergedProperties[key] = {
+              ...mergeSchemas([mergedProperties[key], value]),
+              optional: true
+            };
+          } else {
+            mergedProperties[key] = value;
+          }
+        }
+      }
+    }
+
+    return {
+      type: 'object',
+      properties: mergedProperties
+    };
+  }
+
+  // Mixed types - return union
+  return {
+    type: 'union',
+    schemas
+  };
+}
+
+/**
+ * Create an unknown schema with reason
+ */
+function createUnknownSchema(reason) {
+  return {
+    type: 'unknown',
+    reason
+  };
+}
+
+/**
+ * Convert camelCase to Title Case
+ */
+function camelToTitle(str) {
+  if (!str) return '';
+  return str
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, s => s.toUpperCase())
+    .trim();
+}
+
+/**
+ * Parse all nodes from a module and extract their schemas
+ * @param {Object} nodeDefinitions - Object mapping node names to definitions
+ * @returns {Object} Object mapping node names to schemas
+ */
+export function parseAllNodeSchemas(nodeDefinitions) {
+  const schemas = {};
+
+  for (const [name, definition] of Object.entries(nodeDefinitions)) {
+    schemas[name] = {
+      name: definition.name || name,
+      hasOutputSchema: !!definition.outputSchema,
+      stateSchema: parseNodeSchema(definition)
+    };
+  }
+
+  return schemas;
+}
+
+/**
+ * Convert parsed schema to display-friendly format for Variable Inspector
+ * @param {Object} schema - Parsed schema
+ * @param {string} prefix - Path prefix
+ * @returns {Array} Array of { path, type, label, optional } objects
+ */
+export function schemaToVariables(schema, prefix = '') {
+  const variables = [];
+
+  // Handle union types by merging all object schemas
+  if (schema.type === 'union' && schema.schemas) {
+    const mergedProps = {};
+    for (const subSchema of schema.schemas) {
+      if (subSchema.type === 'object' && subSchema.properties) {
+        for (const [key, propSchema] of Object.entries(subSchema.properties)) {
+          if (!mergedProps[key]) {
+            mergedProps[key] = { ...propSchema, optional: true };
+          }
+        }
+      }
+    }
+    return schemaToVariables({ type: 'object', properties: mergedProps }, prefix);
+  }
+
+  if (schema.type === 'object' && schema.properties) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      const label = propSchema.label || camelToTitle(key);
+
+      variables.push({
+        path,
+        type: propSchema.type,
+        label,
+        optional: propSchema.optional || false
+      });
+
+      // Recurse into nested objects
+      if (propSchema.type === 'object' && propSchema.properties) {
+        variables.push(...schemaToVariables(propSchema, path));
+      }
+      
+      // Recurse into union types within properties
+      if (propSchema.type === 'union' && propSchema.schemas) {
+        const nestedVars = schemaToVariables(propSchema, path);
+        for (const v of nestedVars) {
+          if (!variables.find(existing => existing.path === v.path)) {
+            variables.push(v);
+          }
+        }
+      }
+    }
+  }
+
+  return variables;
+}

package/src/utils/post-process-events.js

@@ -0,0 +1,55 @@
+/**
+ * Post-process events.json to enrich with trace data
+ * This extracts ACTUAL element text from trace for multi-language support
+ */
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { TraceTextEnricher } from '../enrichment/trace-text-enricher.js';
+
+/**
+ * Enrich events.json with actual text from trace
+ * @param {string} sessionPath - Path to session directory (e.g., .../execute_live)
+ * @returns {Promise<{enriched: number, failed: number}>}
+ */
+export async function postProcessEvents(sessionPath) {
+  const eventsPath = join(sessionPath, 'events.json');
+  const enrichedPath = join(sessionPath, 'events-enriched.json');
+  
+  if (!existsSync(eventsPath)) {
+    console.log('[PostProcess] No events.json found');
+    return { enriched: 0, failed: 0 };
+  }
+
+  try {
+    const events = JSON.parse(readFileSync(eventsPath, 'utf-8'));
+    const enricher = new TraceTextEnricher();
+    
+    let enriched = 0;
+    let failed = 0;
+    
+    for (const event of events) {
+      try {
+        const enrichedData = await enricher.enrich(event, { sessionPath });
+        if (enrichedData) {
+          event.enrichedData = { ...(event.enrichedData || {}), ...enrichedData };
+          enriched++;
+        }
+      } catch (e) {
+        console.log(`[PostProcess] Failed to enrich event ${event.id}: ${e.message}`);
+        failed++;
+      }
+    }
+    
+    // Save enriched events (backup original)
+    if (enriched > 0) {
+      writeFileSync(enrichedPath, JSON.stringify(events, null, 2));
+      writeFileSync(eventsPath, JSON.stringify(events, null, 2));
+      console.log(`[PostProcess] ✅ Enriched ${enriched} events (${failed} failed)`);
+    }
+    
+    return { enriched, failed };
+  } catch (e) {
+    console.log(`[PostProcess] ❌ Failed to post-process events: ${e.message}`);
+    return { enriched: 0, failed: 0 };
+  }
+}

package/src/utils/result-handler.js

@@ -0,0 +1,102 @@
+/**
+ * ResultHandler - Generic post-execution logic for any workflow.
+ * Saves results, logs outcomes. Subclass and override onNodeSaved()
+ * for workflow-specific post-processing (event enrichment, video, etc.)
+ */
+
+import { writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { logger } from './logger.js';
+
+export class ResultHandler {
+  /**
+   * Save execution title to session.
+   * Searches state for the first node output containing a 'title' or 'result' string field.
+   */
+  static saveTitle(result, _cwd) {
+    const sessionPath = result.state.sessionPath;
+    if (!sessionPath) return;
+
+    const title = ResultHandler._findInState(result.state, 'title')
+      || ResultHandler._findInState(result.state, 'result');
+    if (!title || typeof title !== 'string') return;
+
+    try {
+      const titlePath = join(sessionPath, 'title.txt');
+      writeFileSync(titlePath, title, 'utf-8');
+      logger.info(`Saved title to session: "${title}"`);
+    } catch (err) {
+      console.warn('⚠️  Could not save title file:', err.message);
+    }
+  }
+
+  static _findInState(state, key) {
+    for (const [, value] of Object.entries(state)) {
+      if (value && typeof value === 'object' && value[key] !== undefined) {
+        return value[key];
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Save execution data for each node that produced actions.
+   * Writes result.json then calls this.onNodeSaved() for subclass processing.
+   */
+  static async saveExecutionData(result) {
+    const sessionPath = result.state.sessionPath;
+    if (!sessionPath) return;
+
+    for (const [nodeName, output] of Object.entries(result.state)) {
+      if (!output || typeof output !== 'object' || !output.actions) continue;
+
+      try {
+        const nodeFolder = join(sessionPath, nodeName);
+        if (!existsSync(nodeFolder)) continue;
+
+        const executionDataPath = join(nodeFolder, 'result.json');
+        writeFileSync(executionDataPath, JSON.stringify(output, null, 2), 'utf-8');
+        logger.info(`Saved execution data to ${nodeName} folder`);
+
+        await this.onNodeSaved(nodeFolder, output);
+      } catch (err) {
+        console.warn(`⚠️  Could not save execution data for ${nodeName}:`, err.message);
+      }
+    }
+  }
+
+  /**
+   * Hook for subclasses -- called after result.json is written for each node.
+   * Override to add enrichment, video processing, etc.
+   */
+  static async onNodeSaved(_nodeFolder, _executionData) {}
+
+  /**
+   * Log workflow result. Inspects all node outputs for success/failure indicators.
+   */
+  static logResult(result, outputPath) {
+    const allOutputs = Object.entries(result.state)
+      .filter(([, v]) => v && typeof v === 'object' && v.success !== undefined);
+
+    const allPassed = allOutputs.length > 0 && allOutputs.every(([, v]) => v.success);
+    const anyFailed = allOutputs.some(([, v]) => v.success === false);
+
+    if (allPassed) {
+      logger.info('Workflow completed successfully.');
+      if (outputPath) logger.info(`Output: ${outputPath}`);
+    } else if (anyFailed) {
+      const failedNodes = allOutputs.filter(([, v]) => !v.success).map(([k]) => k);
+      logger.info(`Workflow completed with failures in: ${failedNodes.join(', ')}`);
+      if (outputPath) logger.info(`Output: ${outputPath}`);
+    }
+
+    return allPassed;
+  }
+
+  static handle(result, cwd, outputPath) {
+    this.saveTitle(result, cwd);
+    this.saveExecutionData(result);
+    const success = this.logResult(result, outputPath);
+    return success;
+  }
+}