@zibby/core 0.1.0

package/src/utils/trace-parser.js

@@ -0,0 +1,325 @@
+/**
+ * TraceParser - Extracts exact selectors from Playwright trace.zip files
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import { tmpdir } from 'os';
+
+export class TraceParser {
+  static async parseTraceZip(traceDirPath) {
+    let traceFilePath;
+    
+    if (traceDirPath.endsWith('.zip') && existsSync(traceDirPath)) {
+      const tempDir = join(tmpdir(), `trace-${Date.now()}`);
+      execSync(`unzip -q "${traceDirPath}" -d "${tempDir}"`, { stdio: 'pipe' });
+      
+      // Find the actual .trace file (trace-{timestamp}.trace, not trace.trace)
+      const files = readdirSync(tempDir);
+      const traceFile = files.find(f => f.endsWith('.trace'));
+      if (!traceFile) throw new Error('No .trace file found in zip');
+      traceFilePath = join(tempDir, traceFile);
+    } else if (existsSync(traceDirPath)) {
+      const files = readdirSync(traceDirPath);
+      const traceFile = files.find(f => f.endsWith('.trace'));
+      if (!traceFile) throw new Error('No .trace file found');
+      traceFilePath = join(traceDirPath, traceFile);
+    } else {
+      throw new Error(`Trace not found at ${traceDirPath}`);
+    }
+
+    try {
+      const traceContent = readFileSync(traceFilePath, 'utf-8');
+      const lines = traceContent.trim().split('\n');
+      const actions = [];
+      
+      // NEW: Extract accessibility tree snapshots (contains ACTUAL text)
+      const accessibilitySnapshots = new Map(); // snapshotName -> Map<ref, node>
+      
+      // Extract DOM snapshots from trace events
+      const domSnapshots = new Map();
+      for (const line of lines) {
+        try {
+          const event = JSON.parse(line);
+          
+          // NEW: Parse accessibility snapshots
+          if (event.type === 'snapshot' && event.snapshot && event.snapshot.accessibility) {
+            const axTree = new Map();
+            for (const node of event.snapshot.accessibility) {
+              if (node.ref) {
+                axTree.set(node.ref, node);
+              }
+            }
+            accessibilitySnapshots.set(event.snapshotName, axTree);
+          }
+          
+          // Look for frame-snapshot events (contains DOM HTML)
+          if (event.type === 'frame-snapshot' && event.snapshot) {
+            const html = Buffer.from(event.snapshot.html || '', 'base64').toString('utf-8');
+            if (html && html.length > 100) { // Only store meaningful snapshots
+              domSnapshots.set(event.pageId || 'default', html);
+            }
+          }
+        } catch {
+          // Ignore snapshot storage errors
+        }
+      }
+
+      for (const line of lines) {
+        try {
+          const event = JSON.parse(line);
+          if (event.type === 'before' && event.params && event.params.selector) {
+            const method = event.method;
+            if (['click', 'fill', 'type', 'selectOption'].includes(method)) {
+              const selector = event.params.selector;
+              const text = event.params.text || event.params.value || '';
+              
+              const strategies = [];
+              
+              // NEW: Extract ACTUAL text from accessibility tree snapshot
+              let actualText = null;
+              let actualRole = null;
+              let actualAriaLabel = null;
+              
+              const ariaRefMatch = selector.match(/aria-ref=([a-z0-9]+)/i);
+              if (ariaRefMatch && event.snapshotName) {
+                const ref = ariaRefMatch[1];
+                const snapshot = accessibilitySnapshots.get(event.snapshotName);
+                if (snapshot && snapshot.has(ref)) {
+                  const node = snapshot.get(ref);
+                  actualText = node.name || null; // ACTUAL text from DOM
+                  actualRole = node.role || null; // ACTUAL role
+                  actualAriaLabel = node.label || null; // ACTUAL aria-label
+                  
+                  console.log(`[TraceParser] ✅ Found ACTUAL element data: text="${actualText}", role="${actualRole}"`);
+                }
+              }
+              
+              // 1. Extract every possible robust anchor from the internal selector
+              const textMatch = selector.match(/internal:text="([^"]+)"/i);
+              const labelMatch = selector.match(/internal:label="([^"]+)"/i);
+              const placeholderMatch = selector.match(/internal:placeholder="([^"]+)"/i);
+              const roleMatch = selector.match(/internal:role=([^ ]+)/i);
+              const describeMatch = selector.match(/internal:describe="([^"]+)"/i);
+              const nameMatch = selector.match(/name="([^"]+)"/i);
+
+              if (textMatch) {
+                strategies.push({ type: 'text', text: textMatch[1] });
+                // Add fuzzy text variants
+                const words = textMatch[1].split(' ');
+                if (words.length > 1) {
+                  strategies.push({ type: 'text', text: words[0], fuzzy: true });
+                  strategies.push({ type: 'text', text: words[words.length - 1], fuzzy: true });
+                }
+              }
+              if (labelMatch) strategies.push({ type: 'label', label: labelMatch[1] });
+              if (placeholderMatch) strategies.push({ type: 'placeholder', placeholder: placeholderMatch[1] });
+              
+              // NEW: PRIORITIZE ACTUAL TEXT from accessibility tree
+              if (actualText) {
+                strategies.unshift({ type: 'text', text: actualText, source: 'accessibility-tree' });
+                // Add fuzzy variants
+                const words = actualText.split(' ');
+                if (words.length > 1) {
+                  strategies.push({ type: 'text', text: words[0], fuzzy: true, source: 'accessibility-tree' });
+                }
+              }
+              
+              if (actualRole || roleMatch) {
+                const role = actualRole || roleMatch[1];
+                const name = actualText || (nameMatch ? nameMatch[1] : (textMatch ? textMatch[1] : null));
+                strategies.unshift({ type: 'role', role, name, source: actualText ? 'accessibility-tree' : 'selector' });
+              }
+              
+              if (actualAriaLabel) {
+                strategies.unshift({ type: 'label', label: actualAriaLabel, source: 'accessibility-tree' });
+              }
+
+              // 2. Parse internal:describe (used by playwright-official)
+              if (describeMatch) {
+                const description = describeMatch[1];
+                const roleKeywords = ['link', 'button', 'textbox', 'menuitem', 'submenu', 'combobox', 'checkbox', 'radio', 'tab', 'treeitem', 'menu item'];
+                
+                // Check if it ends with a role keyword
+                let matchedRole = null;
+                let cleanName = description;
+
+                for (const r of roleKeywords) {
+                  if (description.toLowerCase().endsWith(` ${r}`)) {
+                    matchedRole = r.replace(' ', ''); // Handle "menu item" -> "menuitem"
+                    cleanName = description.substring(0, description.length - r.length - 1);
+                    break;
+                  }
+                }
+
+                if (matchedRole) {
+                  strategies.push({ type: 'role', role: matchedRole, name: cleanName });
+                  // Strip English descriptions in parentheses for cleaner text matching
+                  const textName = cleanName.replace(/\s*\([^)]+\)\s*$/, '');
+                  strategies.push({ type: 'text', text: textName });
+                  strategies.push({ type: 'text', text: cleanName });
+                  
+                  // Add fuzzy text variants
+                  const words = cleanName.split(' ');
+                  if (words.length > 1) {
+                    strategies.push({ type: 'text', text: words[0], fuzzy: true });
+                    strategies.push({ type: 'text', text: words.slice(0, 2).join(' '), fuzzy: true });
+                  }
+                } else {
+                  const textName = description.replace(/\s*\([^)]+\)\s*$/, '');
+                  strategies.push({ type: 'text', text: textName });
+                  strategies.push({ type: 'text', text: description });
+                }
+              }
+
+              // 3. Extract data-testid, classes, IDs from DOM snapshots
+              const domStrategies = this.extractDOMStrategies(selector, domSnapshots, textMatch?.[1] || describeMatch?.[1], event.pageId);
+              strategies.push(...domStrategies);
+
+              // Extract structural context (parent/sibling) from CSS selector chain
+              const structuralContext = this.extractStructuralContext(selector);
+              
+              // Add structural context to high-priority strategies
+              if (structuralContext.parent || structuralContext.sibling) {
+                strategies.forEach(strat => {
+                  if (['role', 'text', 'label', 'testid'].includes(strat.type)) {
+                    if (structuralContext.parent) strat.parent = structuralContext.parent;
+                    if (structuralContext.sibling) strat.sibling = structuralContext.sibling;
+                  }
+                });
+              }
+              
+              // Always add the raw CSS as a final fallback
+              strategies.push({ type: 'css', value: selector });
+              
+              // NEW: Use ACTUAL text if available, fallback to AI description
+              const finalName = actualText || 
+                               textMatch ? textMatch[1] : 
+                               (describeMatch ? describeMatch[1].replace(/\s*\([^)]+\)\s*$/, '') : 
+                               `Action ${actions.length}`);
+              
+              actions.push({
+                method,
+                name: finalName,
+                action: method === 'type' ? 'fill' : method,
+                value: text,
+                strategies,
+                timestamp: event.startTime,
+                // NEW: Include metadata for debugging
+                actualText,
+                actualRole,
+                actualAriaLabel
+              });
+            }
+          }
+        } catch {
+          // Ignore trace entry parsing errors
+        }
+      }
+      return actions;
+    } catch (error) {
+      throw new Error(`Failed to parse trace: ${error.message}`, { cause: error });
+    }
+  }
+
+  /**
+   * Extract data-testid, classes, IDs, and DOM paths from snapshots
+   */
+  static extractDOMStrategies(selector, domSnapshots, textHint, pageId) {
+    const strategies = [];
+    
+    if (!domSnapshots || domSnapshots.size === 0 || !textHint) {
+      return strategies;
+    }
+    
+    try {
+      // Get the snapshot for this page
+      const html = domSnapshots.get(pageId);
+      if (!html) {
+        return strategies;
+      }
+      
+      // Escape special regex characters in textHint
+      const escapedHint = textHint.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      
+      // Extract data-testid patterns
+      const testidRegex = new RegExp(`data-testid=["']([^"']+)["'][^>]*>[^<]*${escapedHint}`, 'i');
+      const testidMatch = html.match(testidRegex);
+      if (testidMatch) {
+        strategies.push({ type: 'testid', value: testidMatch[1], priority: 'high' });
+      }
+      
+      // Extract stable class names (not dynamic like css-123abc)
+      const classRegex = new RegExp(`class=["']([^"']+)["'][^>]*>[^<]*${escapedHint}`, 'gi');
+      const classMatches = html.matchAll(classRegex);
+      for (const match of classMatches) {
+        const classes = match[1].split(/\s+/).filter(c => 
+          c && !c.match(/^(css|jss|makeStyles|MuiBox|MuiStack)-\w+/) && c.length > 2
+        );
+        if (classes.length > 0) {
+          strategies.push({ type: 'class', value: classes.join('.'), priority: 'medium' });
+          if (classes.length === 1) {
+            strategies.push({ type: 'class', value: classes[0], priority: 'medium' });
+          }
+        }
+      }
+      
+      // Extract stable IDs (not dynamic)
+      const idRegex = new RegExp(`id=["']([^"']+)["'][^>]*>[^<]*${escapedHint}`, 'i');
+      const idMatch = html.match(idRegex);
+      if (idMatch && !idMatch[1].match(/^(root|app|\d+|[a-f0-9-]{20,})$/i)) {
+        strategies.push({ type: 'id', value: idMatch[1], priority: 'high' });
+      }
+      
+    } catch (e) {
+      // Silent fail - snapshots are optional enhancement
+      console.warn(`[TraceParser] DOM extraction failed: ${e.message}`);
+    }
+    
+    return strategies;
+  }
+
+  /**
+   * Extract parent/sibling context from Playwright internal selector chains
+   * Example: "form[name='login'] >> button" => parent: "form[name='login']"
+   */
+  static extractStructuralContext(selector) {
+    const context = { parent: null, sibling: null };
+    
+    // Split by >> to get hierarchy (Playwright's chaining operator)
+    const parts = selector.split('>>').map(p => p.trim());
+    
+    if (parts.length > 1) {
+      // The second-to-last part is likely the parent container
+      const parentPart = parts[parts.length - 2];
+      
+      // Extract clean CSS from internal: prefixes
+      const cleanParent = parentPart
+        .replace(/internal:text="[^"]+"\s*/gi, '')
+        .replace(/internal:role=\S+\s*/gi, '')
+        .replace(/internal:label="[^"]+"\s*/gi, '')
+        .trim();
+      
+      // Only use if it's a meaningful selector (form, div with id/class, etc)
+      if (cleanParent && (
+        cleanParent.match(/^(form|section|nav|header|aside|main|article)\b/) ||
+        cleanParent.includes('[') ||
+        cleanParent.match(/[#.]\w/)
+      )) {
+        context.parent = cleanParent;
+      }
+    }
+    
+    // Extract sibling hints from CSS selectors like "input[type='email'] + button"
+    const lastPart = parts[parts.length - 1];
+    const siblingMatch = lastPart.match(/([^+~]+)\s*[+~]\s*(.+)/);
+    if (siblingMatch) {
+      context.sibling = siblingMatch[1].trim();
+    }
+    
+    return context;
+  }
+}
+
+export default TraceParser;

package/src/utils/video-organizer.js

@@ -0,0 +1,91 @@
+import { readdir, access, copyFile, constants } from 'fs/promises';
+import { join, relative } from 'path';
+
+export async function organizeVideos(options = {}) {
+  const {
+    testResultsDir = 'test-results',
+    testsDir = 'tests',
+    projectRoot = process.cwd(),
+    verbose = true,
+  } = options;
+
+  if (verbose) {
+    console.log('🎥 Organizing test videos...\n');
+  }
+
+  const resultsPath = join(projectRoot, testResultsDir);
+  const testsPath = join(projectRoot, testsDir);
+
+  try {
+    const results = await readdir(resultsPath);
+    let movedCount = 0;
+
+    for (const resultDir of results) {
+      if (resultDir.startsWith('.')) continue;
+
+      const videoPath = join(resultsPath, resultDir, 'video.webm');
+
+      try {
+        await access(videoPath, constants.F_OK);
+      } catch {
+        continue;
+      }
+
+      const testName = resultDir
+        .replace(/-chromium$/, '')
+        .replace(/-firefox$/, '')
+        .replace(/-webkit$/, '');
+
+      const testFile = await findTestFile(testsPath, testName);
+
+      if (testFile) {
+        const videoName = testFile.replace(/\.spec\.(js|ts)$/, '.spec.webm');
+
+        await copyFile(videoPath, videoName);
+        
+        if (verbose) {
+          console.log(`✅ ${relative(projectRoot, videoName)}`);
+        }
+        
+        movedCount++;
+      } else if (verbose) {
+        console.log(`⚠️  Could not find test file for: ${resultDir}`);
+      }
+    }
+
+    if (verbose) {
+      console.log(`\n🎬 Organized ${movedCount} video(s)`);
+      console.log(`📂 Videos are now next to their test files in ${testsDir}/`);
+    }
+
+    return { movedCount, success: true };
+
+  } catch (error) {
+    if (verbose) {
+      console.error('❌ Error organizing videos:', error.message);
+    }
+    return { movedCount: 0, success: false, error: error.message };
+  }
+}
+
+async function findTestFile(testsDir, testName) {
+  const parts = testName.split('-');
+
+  for (let i = parts.length; i > 0; i--) {
+    const pathParts = parts.slice(0, i);
+    const searchPath = pathParts.join('/');
+
+    for (const ext of ['js', 'ts']) {
+      const testPath = join(testsDir, `${searchPath}.spec.${ext}`);
+      try {
+        await access(testPath, constants.F_OK);
+        return testPath;
+      } catch {
+        // File doesn't exist, continue search
+      }
+    }
+  }
+
+  return null;
+}
+

package/templates/browser-test-automation/README.md

@@ -0,0 +1,114 @@
+# Browser Test Automation Workflow
+
+This is YOUR workflow graph. You can customize it however you want!
+
+Works with **Claude** or **Cursor** agents (configured in `.zibby.config.js`).
+
+## Default Flow
+
+```
+preflight → execute_live → generate_script
+```
+
+The workflow generates a test title, executes the test live in a **browser** with AI assistance, and generates a Playwright script with stable selectors.
+
+## Customization
+
+### Add Custom Nodes
+
+Create a new file in `nodes/`:
+
+```javascript
+// nodes/send-slack.js
+export const sendSlackNode = {
+  name: 'send_slack',
+  agent: { type: 'openai', model: 'gpt-4o-mini' },
+  prompt: (state) => `Send Slack notification...`,
+  outputSchema: { success: { type: 'boolean', required: true } }
+};
+```
+
+Then add it to your graph in `graph.js`:
+
+```javascript
+import { sendSlackNode } from './nodes/send-slack.js';
+
+buildGraph() {
+  const graph = new WorkflowGraph();
+  // ... existing nodes
+  graph.addNode('send_slack', sendSlackNode);
+  graph.addEdge('verify_script', 'send_slack');
+  return graph;
+}
+```
+
+### Multi-Agent Configuration
+
+Each node can use a different LLM:
+
+```javascript
+graph.addNode('generate_title', {
+  agent: { type: 'claude', model: 'claude-sonnet-4' },
+  prompt: (state) => `Generate title...`
+});
+
+graph.addNode('verify_script', {
+  agent: { type: 'deepseek', model: 'deepseek-coder' }, // Cheap & fast
+  prompt: (state) => `Run test...`
+});
+
+graph.addNode('update_jira', {
+  agent: { type: 'ollama', model: 'llama3' }, // Local for privacy
+  prompt: (state) => `Update Jira...`
+});
+```
+
+### Skip Nodes
+
+Comment out nodes you don't need:
+
+```javascript
+// graph.addNode('verify_script', verifyScriptNode);
+graph.addEdge('generate_script', 'update_jira'); // Skip verification
+```
+
+### Parallel Execution
+
+Run multiple nodes in parallel:
+
+```javascript
+graph.addParallelEdges('verify_script', [
+  'send_slack',
+  'update_jira',
+  'log_datadog'
+]);
+```
+
+## Configuration
+
+Edit `.zibby/config.js` to set default agents per node:
+
+```javascript
+export default {
+  agents: {
+    execute_live: { type: 'cursor' },
+    verify_script: { type: 'deepseek', model: 'deepseek-coder' },
+    update_jira: { type: 'ollama', model: 'llama3' }
+  }
+};
+```
+
+## Documentation
+
+- [Full Graph Framework Design](../../docs/GRAPH_FRAMEWORK_DESIGN.md)
+- [Multi-Agent Patterns](../../docs/FRAMEWORK_CONVERSATION_SUMMARY.md)
+
+## Updates
+
+To get latest template updates:
+
+```bash
+zibby update-graph --merge
+```
+
+This will merge bug fixes while preserving your customizations.

package/templates/browser-test-automation/graph.js

@@ -0,0 +1,54 @@
+/**
+ * Test Automation Workflow Graph
+ * 
+ * buildGraph() - define nodes, edges, routing
+ * onComplete(result) - post-processing after graph finishes (save artifacts, etc.)
+ */
+
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { memoryMiddleware } from '@zibby/memory';
+import { 
+  preflightNode, 
+  executeLiveNode, 
+  generateScriptNode,
+} from './nodes/index.js';
+import { BrowserTestResultHandler } from './result-handler.js';
+
+export class BrowserTestAutomationAgent extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph({
+      middleware: [memoryMiddleware()].filter(Boolean),
+    });
+
+    graph.addNode('preflight', preflightNode);
+    graph.addNode('execute_live', executeLiveNode);
+    graph.addNode('generate_script', generateScriptNode);
+            
+    graph.setEntryPoint('preflight');
+    graph.addEdge('preflight', 'execute_live');
+    
+    graph.addConditionalEdges('execute_live', (state) => {
+      const result = state.execute_live;
+      const hasExecution = (result?.steps?.length > 0) || (result?.actions?.length > 0);
+      return hasExecution ? 'generate_script' : 'END';
+    });
+    
+    graph.addEdge('generate_script', 'END');
+    return graph;
+  }
+
+  async onComplete(result) {
+    const cwd = result.state.cwd || process.cwd();
+    BrowserTestResultHandler.saveTitle(result, cwd);
+    await BrowserTestResultHandler.saveExecutionData(result);
+
+    if (process.env.ZIBBY_MEMORY) {
+      try {
+        const { memoryEndRun, memorySyncPush } = await import('@zibby/memory');
+        const sessionId = result.state.sessionPath?.split('/').pop();
+        memoryEndRun(cwd, { sessionId, passed: result.success !== false });
+        memorySyncPush(cwd);
+      } catch { /* @zibby/memory not available */ }
+    }
+  }
+}