@zibby/core 0.1.0

package/src/enrichment/mcp-integration.js

@@ -0,0 +1,149 @@
+/**
+ * MCP Recorder Integration with Enrichment Pipeline
+ * 
+ * This module provides utilities to enrich MCP-recorded events
+ * after test execution (when we have access to trace data)
+ */
+
+import { createDefaultPipeline, createMinimalPipeline } from './index.js';
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Enrich recorded events.json file with data from Playwright trace
+ * 
+ * @param {string} sessionPath - Path to session directory
+ * @param {Object} config - Enrichment configuration
+ * @returns {Promise<Object>} - { enrichedCount, skippedCount, errors }
+ */
+export async function enrichRecordedEvents(sessionPath, _config = {}) {
+  const eventsPath = join(sessionPath, 'events.json');
+  const _tracePath = join(sessionPath, 'trace.zip');
+  
+  try {
+    // Read events
+    const events = JSON.parse(readFileSync(eventsPath, 'utf-8'));
+    
+    // For now, we add placeholder enrichment metadata
+    // Full enrichment requires re-playing with Playwright access
+    const enriched = events.map(event => ({
+      ...event,
+      _enrichmentNote: 'Full enrichment requires live Playwright access. Use EnrichmentPipeline during test execution.'
+    }));
+    
+    // Save enriched events
+    const backupPath = `${eventsPath  }.backup`;
+    writeFileSync(backupPath, JSON.stringify(events, null, 2));
+    writeFileSync(eventsPath, JSON.stringify(enriched, null, 2));
+    
+    return {
+      enrichedCount: enriched.length,
+      skippedCount: 0,
+      errors: []
+    };
+  } catch (error) {
+    console.error('[EnrichmentIntegration] Failed to enrich events:', error.message);
+    return {
+      enrichedCount: 0,
+      skippedCount: 0,
+      errors: [error.message]
+    };
+  }
+}
+
+/**
+ * Example: How to use enrichment pipeline during live test execution
+ * 
+ * This is a reference implementation for integrating enrichment
+ * into your test execution flow where you have Playwright access.
+ */
+export class LiveEnrichmentRecorder {
+  constructor(config = {}) {
+    // Create enrichment pipeline
+    this.pipeline = config.minimal 
+      ? createMinimalPipeline(config)
+      : createDefaultPipeline(config);
+    
+    this.events = [];
+    this.config = config;
+  }
+
+  /**
+   * Record and enrich an event during test execution
+   * 
+   * @param {string} type - Event type (click, fill, etc)
+   * @param {Object} data - Event data
+   * @param {Object} context - { page, element, ref }
+   * @returns {Promise<Object>} - Enriched event
+   */
+  async recordEvent(type, data, context) {
+    // Create base event (MCP format)
+    const baseEvent = {
+      id: this.events.length,
+      type,
+      timestamp: new Date().toISOString(),
+      data
+    };
+    
+    // Enrich with pipeline
+    const enriched = await this.pipeline.enrich(baseEvent, {
+      ...context,
+      event: baseEvent
+    });
+    
+    this.events.push(enriched);
+    return enriched;
+  }
+
+  /**
+   * Save enriched events to file
+   * @param {string} filePath
+   */
+  saveEvents(filePath) {
+    writeFileSync(filePath, JSON.stringify(this.events, null, 2));
+    console.log(`[LiveEnrichment] Saved ${this.events.length} enriched events to ${filePath}`);
+    
+    // Log statistics
+    this.pipeline.logStatus();
+  }
+
+  /**
+   * Get pipeline statistics
+   */
+  getStats() {
+    return this.pipeline.getStats();
+  }
+}
+
+/**
+ * Example integration with Cursor Agent workflow
+ * 
+ * Usage in execute_live node:
+ * 
+ * ```javascript
+ * import { LiveEnrichmentRecorder } from '@zibby/core';
+ * 
+ * const recorder = new LiveEnrichmentRecorder({ minimal: true });
+ * 
+ * // During test execution (when you have page/element access):
+ * const page = await browser.newPage();
+ * const element = await page.locator('button');
+ * 
+ * // Record enriched event
+ * await recorder.recordEvent('click', {
+ *   tool: 'browser_click',
+ *   params: { element: 'Submit button', ref: 'k123' }
+ * }, {
+ *   page,
+ *   element
+ * });
+ * 
+ * // Save at end
+ * recorder.saveEvents('enriched-events.json');
+ * ```
+ */
+
+export default {
+  enrichRecordedEvents,
+  LiveEnrichmentRecorder
+};

package/src/enrichment/mcp-ref-enricher.js

@@ -0,0 +1,78 @@
+import { EventEnricher } from './base.js';
+
+/**
+ * MCPRefEnricher - Captures ACTUAL element text from trace DOM snapshots
+ * 
+ * Problem: AI might say "Login button" but actual button text is "登录" (Chinese)
+ * Solution: Extract the REAL text from trace DOM snapshot at action time
+ * 
+ * Priority order:
+ * 1. Extract actual text/label from trace DOM snapshot (handles Chinese/any language)
+ * 2. Fall back to MCP element description (AI's description)
+ * 
+ * This ensures Chinese, Arabic, Japanese, etc. apps work perfectly!
+ */
+export class MCPRefEnricher extends EventEnricher {
+  constructor(config = {}) {
+    super(config);
+    this.priority = 200; // Highest priority
+  }
+
+  getName() {
+    return 'MCPRef';
+  }
+
+  getPriority() {
+    return this.priority;
+  }
+
+  async enrich(event, context) {
+    const ref = event.data?.params?.ref;
+    const mcpElement = event.data?.params?.element; // What AI said
+    
+    if (!ref && !mcpElement) {
+      return null;
+    }
+
+    // Try to extract ACTUAL element properties from the DOM (if we have element access)
+    let actualText = null;
+    let actualRole = null;
+    let actualLabel = null;
+    
+    if (context?.element) {
+      try {
+        // Extract the REAL text that user sees (not what AI said)
+        const elementData = await context.element.evaluate(el => {
+          return {
+            text: el.textContent?.trim() || '',
+            innerText: el.innerText?.trim() || '',
+            value: el.value || '',
+            label: el.getAttribute('aria-label') || el.getAttribute('label') || '',
+            role: el.getAttribute('role') || el.tagName.toLowerCase(),
+            placeholder: el.getAttribute('placeholder') || '',
+            title: el.getAttribute('title') || ''
+          };
+        });
+        
+        // Use the most specific text we can find
+        actualText = elementData.text || elementData.innerText || elementData.value || elementData.placeholder;
+        actualRole = elementData.role;
+        actualLabel = elementData.label || elementData.title;
+        
+        console.log(`[MCPRefEnricher] ✅ Captured actual text: "${actualText}" (AI said: "${mcpElement}")`);
+      } catch (e) {
+        console.log(`[MCPRefEnricher] ⚠️  Could not extract actual text: ${e.message}`);
+      }
+    }
+
+    return {
+      mcpRef: ref,
+      mcpElement,           // What AI said (might be translated)
+      actualText,            // ✅ REAL text from DOM (Chinese/any language)
+      actualRole,            // ✅ REAL role (button, link, textbox)
+      actualLabel,          // ✅ REAL aria-label
+      // Use actual text if available, otherwise fall back to AI's description
+      recordedSelector: actualText || mcpElement
+    };
+  }
+}

package/src/enrichment/pipeline.js

@@ -0,0 +1,192 @@
+/**
+ * Enrichment Pipeline Manager
+ * Orchestrates multiple enrichers to add data to events
+ */
+
+export class EnrichmentPipeline {
+  constructor(config = {}) {
+    this.enrichers = [];
+    this.config = config;
+    this.stats = {
+      totalEvents: 0,
+      enrichedEvents: 0,
+      skippedEvents: 0,
+      errors: {}
+    };
+  }
+
+  /**
+   * Register an enricher
+   * @param {EventEnricher} enricher
+   */
+  register(enricher) {
+    this.enrichers.push(enricher);
+    // Sort by priority (highest first)
+    this.enrichers.sort((a, b) => b.getPriority() - a.getPriority());
+    return this;
+  }
+
+  /**
+   * Unregister an enricher by name
+   * @param {string} name
+   */
+  unregister(name) {
+    this.enrichers = this.enrichers.filter(e => e.getName() !== name);
+    return this;
+  }
+
+  /**
+   * Get enricher by name
+   * @param {string} name
+   */
+  get(name) {
+    return this.enrichers.find(e => e.getName() === name);
+  }
+
+  /**
+   * Enable/disable specific enricher
+   * @param {string} name
+   * @param {boolean} enabled
+   */
+  setEnabled(name, enabled) {
+    const enricher = this.get(name);
+    if (enricher) {
+      enricher.enabled = enabled;
+    }
+    return this;
+  }
+
+  /**
+   * Enrich an event through the pipeline
+   * @param {Object} event - MCP event
+   * @param {Object} context - { page, element, ref, session }
+   * @returns {Promise<Object>} - Enriched event
+   */
+  async enrich(event, context) {
+    this.stats.totalEvents++;
+    
+    // Start with original event
+    const enriched = { ...event };
+    
+    // Track which enrichers ran
+    const enrichersRun = [];
+    const enrichersSkipped = [];
+    const enrichersFailed = [];
+    
+    // Run each enricher in priority order
+    for (const enricher of this.enrichers) {
+      try {
+        // Check if enricher can run
+        if (!enricher.canEnrich(context)) {
+          enrichersSkipped.push(enricher.getName());
+          continue;
+        }
+        
+        // Run enricher
+        const startTime = Date.now();
+        const data = await enricher.enrich(event, context);
+        const duration = Date.now() - startTime;
+        
+        if (data) {
+          // Merge enriched data
+          Object.assign(enriched, data);
+          enrichersRun.push({ name: enricher.getName(), duration });
+        } else {
+          enrichersSkipped.push(enricher.getName());
+        }
+      } catch (error) {
+        console.warn(`[EnrichmentPipeline] ${enricher.getName()} failed:`, error.message);
+        enrichersFailed.push(enricher.getName());
+        
+        // Track errors
+        this.stats.errors[enricher.getName()] = (this.stats.errors[enricher.getName()] || 0) + 1;
+      }
+    }
+    
+    // Add enrichment metadata
+    enriched._enrichment = {
+      version: '1.0',
+      timestamp: new Date().toISOString(),
+      enrichers: {
+        run: enrichersRun,
+        skipped: enrichersSkipped,
+        failed: enrichersFailed
+      }
+    };
+    
+    // Update stats
+    if (enrichersRun.length > 0) {
+      this.stats.enrichedEvents++;
+    } else {
+      this.stats.skippedEvents++;
+    }
+    
+    return enriched;
+  }
+
+  /**
+   * Enrich multiple events in batch
+   * @param {Array} events
+   * @param {Object} context
+   * @returns {Promise<Array>}
+   */
+  async enrichBatch(events, context) {
+    const results = [];
+    
+    for (const event of events) {
+      const enriched = await this.enrich(event, context);
+      results.push(enriched);
+    }
+    
+    return results;
+  }
+
+  /**
+   * Get pipeline statistics
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      enrichers: this.enrichers.map(e => ({
+        name: e.getName(),
+        enabled: e.enabled,
+        priority: e.getPriority(),
+        errors: this.stats.errors[e.getName()] || 0
+      }))
+    };
+  }
+
+  /**
+   * Reset statistics
+   */
+  resetStats() {
+    this.stats = {
+      totalEvents: 0,
+      enrichedEvents: 0,
+      skippedEvents: 0,
+      errors: {}
+    };
+  }
+
+  /**
+   * Log pipeline status
+   */
+  logStatus() {
+    console.log('\n📊 Enrichment Pipeline Status:');
+    console.log(`   Total events: ${this.stats.totalEvents}`);
+    console.log(`   Enriched: ${this.stats.enrichedEvents}`);
+    console.log(`   Skipped: ${this.stats.skippedEvents}`);
+    console.log(`\n   Registered enrichers (${this.enrichers.length}):`);
+    
+    for (const enricher of this.enrichers) {
+      const status = enricher.enabled ? '✓' : '✗';
+      const errors = this.stats.errors[enricher.getName()] || 0;
+      const errorStr = errors > 0 ? ` (${errors} errors)` : '';
+      console.log(`     ${status} ${enricher.getName()} (priority: ${enricher.getPriority()})${errorStr}`);
+    }
+    
+    console.log();
+  }
+}
+
+export default EnrichmentPipeline;

package/src/enrichment/trace-text-enricher.js

@@ -0,0 +1,115 @@
+import { EventEnricher } from './base.js';
+import { TraceParser } from '../utils/trace-parser.js';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * TraceTextEnricher - Extracts ACTUAL element text from Playwright trace
+ * 
+ * Problem: AI might say "Login button" but actual DOM has "登录" (Chinese)
+ * Solution: Parse trace.zip to find the actual element text at action time
+ * 
+ * This runs AFTER recording as a post-processing step.
+ */
+export class TraceTextEnricher extends EventEnricher {
+  constructor(config = {}) {
+    super(config);
+    this.priority = 190; // Just below MCPRefEnricher
+    this.traceData = null;
+  }
+
+  getName() {
+    return 'TraceText';
+  }
+
+  getPriority() {
+    return this.priority;
+  }
+
+  /**
+   * Load trace data once for all events
+   */
+  async loadTrace(sessionPath) {
+    if (this.traceData) return;
+
+    const _tracePath = join(sessionPath, 'traces');
+    const traceZipPath = join(sessionPath, 'trace.zip');
+    
+    if (existsSync(traceZipPath)) {
+      try {
+        this.traceData = await TraceParser.parseTraceZip(traceZipPath);
+        console.log(`[TraceTextEnricher] ✅ Loaded trace with ${this.traceData.length} actions`);
+      } catch (e) {
+        console.log(`[TraceTextEnricher] ⚠️  Failed to parse trace: ${e.message}`);
+      }
+    }
+  }
+
+  async enrich(event, context) {
+    const ref = event.data?.params?.ref;
+    const eventId = event.id;
+    if (ref === undefined && eventId === undefined) return null;
+
+    // Load trace on first event
+    if (!this.traceData && context.sessionPath) {
+      await this.loadTrace(context.sessionPath);
+    }
+
+    if (!this.traceData) return null;
+
+    // Match by sequence order: event.id maps to traceData[id]
+    // This is more reliable than matching by ref (which trace doesn't have)
+    const traceAction = this.traceData[eventId];
+    if (!traceAction) {
+      console.log(`[TraceTextEnricher] ⚠️  No trace action for event ${eventId}`);
+      return null;
+    }
+
+    // NEW: Use the actualText extracted from accessibility tree
+    const actualText = traceAction.actualText || this._extractTextFromSelector(traceAction.selector);
+    const actualRole = traceAction.actualRole;
+    const actualAriaLabel = traceAction.actualAriaLabel;
+    
+    if (actualText || actualRole || actualAriaLabel) {
+      console.log(`[TraceTextEnricher] ✅ Event ${eventId}: text="${actualText}", role="${actualRole}", label="${actualAriaLabel}"`);
+      return {
+        traceActualText: actualText,
+        traceActualRole: actualRole,
+        traceActualAriaLabel: actualAriaLabel,
+        traceSelector: traceAction.selector,
+        traceStrategies: traceAction.strategies // Include all strategies
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Extract actual text from Playwright's internal selector format
+   * Examples:
+   * - internal:label="登录" -> "登录"
+   * - getByText('Submit') -> "Submit"
+   * - getByRole('button', { name: '确定' }) -> "确定"
+   */
+  _extractTextFromSelector(selector) {
+    if (!selector) return null;
+
+    // Try internal:label format
+    const labelMatch = selector.match(/internal:label="([^"]+)"/);
+    if (labelMatch) return labelMatch[1];
+
+    // Try internal:text format
+    const textMatch = selector.match(/internal:text="([^"]+)"/);
+    if (textMatch) return textMatch[1];
+
+    // Try getByText format
+    const getByTextMatch = selector.match(/getByText\(['"]([^'"]+)['"]\)/);
+    if (getByTextMatch) return getByTextMatch[1];
+
+    // Try getByRole with name format
+    const getByRoleMatch = selector.match(/name:\s*['"]([^'"]+)['"]/);
+    if (getByRoleMatch) return getByRoleMatch[1];
+
+    return null;
+  }
+}

package/src/framework/AGENTS.md

@@ -0,0 +1,98 @@
+# Workflow Execution Architecture
+
+## Single Source of Truth: Template Node Files
+
+Workflows are **compiled from source code**, not loaded from JSON files.
+
+The template node definitions in `packages/core/templates/` are the single source of truth.
+There is no static JSON workflow file — any such file (e.g. `default-analysis-workflow.json`) is stale and unused.
+
+## How It Works
+
+### 1. Graph Builders Compile Templates into Workflows
+
+Each workflow type has a graph builder that imports node definitions and wires them together:
+
+```
+packages/core/templates/code-analysis/graph.js     → buildAnalysisGraph()
+packages/core/templates/code-implementation/graph.js → buildImplementationGraph()
+```
+
+These builders import the actual node files:
+
+```
+packages/core/templates/code-analysis/nodes/
+  ├── setup-node.js
+  ├── analyze-ticket-node.js
+  ├── generate-code-node.js
+  ├── generate-test-cases-node.js
+  └── finalize-node.js
+```
+
+Each node file exports `{ name, outputSchema, execute }`. The `execute` function is the actual runtime code.
+
+### 2. Backend Resolves Workflow at Execution Time
+
+When a user triggers an analysis (`POST /projects/:projectId/tickets/:ticketKey/analyze`), the backend resolves the workflow in this order:
+
+1. **WORKFLOWS_TABLE** (DynamoDB) — user-customized workflow saved via the UI workflow editor
+2. **project.analysisGraphConfig** (PROJECTS_TABLE) — legacy per-project config
+3. **null** — no saved workflow; the CLI will use the compiled default
+
+The resolved config (or null) is uploaded to S3 as `context.json` and passed to the ECS container via `CONTEXT_PRESIGNED_URL`.
+
+### 3. ECS Container Compiles and Runs the Graph
+
+The CLI (`packages/cli/src/commands/analyze-graph.js`) picks the workflow source:
+
+```
+if (options.workflow)        → local file (--workflow flag, dev only)
+else if (execCtx.graphConfig) → custom saved workflow from DynamoDB (serialized JSON)
+else                          → getDefaultGraph('analysis') → buildAnalysisGraph() from templates
+```
+
+When using the default path, `buildAnalysisGraph()` imports the node files directly — the `execute` functions run as compiled JavaScript, not as eval'd strings.
+
+When using a saved custom workflow, `compileGraph()` deserializes the JSON and wraps `executeCode` strings via `new Function()`.
+
+### 4. Key Implication: Saved Workflows Can Go Stale
+
+If a user saves a workflow via the UI editor, the `executeCode` is serialized as a string snapshot into DynamoDB. Future code fixes to the template node files **do not** propagate to saved workflows.
+
+**To pick up template fixes**: reset the workflow in the UI settings (Project → Settings → Workflow → Reset to Default). This deletes the DynamoDB record and forces the CLI to recompile from templates.
+
+## State Access Pattern
+
+The graph stores each node's output under `state[nodeName]`:
+
+```js
+// In graph.js after node execution:
+state.update({ [currentNode]: result.output });
+
+// So to access previous node results:
+state.analyze_ticket?.analysis        // NOT state.analysis
+state.generate_code?.codeImplementation  // NOT state.codeImplementation
+```
+
+## invokeAgent Return Shape
+
+When `invokeAgent` is called with a `schema` option, it returns `{ raw, structured }` (not the structured data directly):
+
+```js
+const result = await invokeAgent(prompt, { state, model, schema: SomeSchema });
+const output = result?.structured || result;  // unwrap
+```
+
+Without a schema, it returns a plain string.
+
+## File-Based Structured Output (Cursor Strategy)
+
+For Cursor agent, structured output uses a file-based approach:
+
+1. Framework generates a unique file path: `.zibby/tmp/zibby-result-<timestamp>.json`
+2. Instructions appended to prompt telling agent to write JSON to that file
+3. After agent completes, framework reads the file and validates with Zod
+4. If validation fails and `strictMode` is enabled, falls back to OpenAI proxy for schema enforcement
+5. Result files are kept (not deleted) for debugging
+
+The Claude strategy uses its SDK's native structured output — completely separate path.

package/src/framework/agents/base.js

@@ -0,0 +1,72 @@
+/**
+ * Base class for AI agent strategies.
+ * All provider implementations (Cursor, Claude, etc.) must extend this class.
+ *
+ * @abstract
+ */
+export class AgentStrategy {
+  /**
+   * @param {string} name - Provider identifier (e.g. 'cursor', 'claude')
+   * @param {string} description - Human-readable description
+   * @param {number} [priority=0] - Selection priority (higher = preferred)
+   */
+  constructor(name, description, priority = 0) {
+    this.name = name;
+    this.description = description;
+    this.priority = priority;
+  }
+
+  /**
+   * Execute a prompt against this agent.
+   *
+   * @abstract
+   * @param {string} prompt - The prompt text
+   * @param {AgentInvokeOptions} options
+   * @returns {Promise<string | AgentStructuredResult>}
+   *   - Without schema: returns raw output string
+   *   - With schema: returns { raw: string, structured: object }
+   *   - On failure: throws Error
+   *
+   * @typedef {Object} AgentInvokeOptions
+   * @property {string}  [model]       - Model name or 'auto'
+   * @property {string}  [workspace]   - Working directory
+   * @property {object}  [schema]      - Zod schema for structured output
+   * @property {Array}   [tools]       - MCP tools available to the agent
+   * @property {Array}   [images]      - Image attachments (provider-specific)
+   * @property {string}  [sessionPath] - Session artifact directory
+   * @property {number}  [timeout]     - Execution timeout in ms
+   * @property {object}  [config]      - Full workflow config
+   *
+   * @typedef {Object} AgentStructuredResult
+   * @property {string} raw        - Raw agent output
+   * @property {object} structured - Parsed and validated output
+   */
+  async invoke(prompt, _options = {}) {
+    throw new Error('AgentStrategy.invoke() must be implemented by subclass');
+  }
+
+  /**
+   * Check if this agent strategy is available in the current environment.
+   *
+   * @abstract
+   * @param {object} [context] - Environment context (unused by most providers)
+   * @returns {boolean}
+   */
+  canHandle(_context) {
+    throw new Error('AgentStrategy.canHandle() must be implemented by subclass');
+  }
+
+  getName() {
+    return this.name;
+  }
+
+  getDescription() {
+    return this.description;
+  }
+
+  getPriority() {
+    return this.priority;
+  }
+}
+
+export default AgentStrategy;