@zibby/core 0.1.0

package/src/runtime/verification/index.js

@@ -0,0 +1,67 @@
+/**
+ * Test Verification Strategy Manager
+ * Automatically selects and runs the best available verification strategy
+ */
+import { PlaywrightJsonVerificationStrategy } from './playwright-json-strategy.js';
+
+export class TestVerificationStrategyManager {
+  constructor() {
+    // Register all available strategies
+    this.strategies = [
+      new PlaywrightJsonVerificationStrategy(),
+    ];
+
+    // Sort by priority (highest first)
+    this.strategies.sort((a, b) => b.getPriority() - a.getPriority());
+  }
+
+  /**
+   * Add a custom strategy
+   * @param {TestVerificationStrategy} strategy
+   */
+  registerStrategy(strategy) {
+    this.strategies.push(strategy);
+    this.strategies.sort((a, b) => b.getPriority() - a.getPriority());
+  }
+
+  /**
+   * Verify test using the best available strategy
+   * @param {Object} context - Verification context
+   * @returns {Promise<Object>} - Verification result
+   */
+  async verify(context) {
+    console.log(`\n📋 Available verification strategies (${this.strategies.length}):`);
+    this.strategies.forEach(s => {
+      const canUse = s.canVerify(context);
+      console.log(`   ${canUse ? '✓' : '✗'} ${s.getName()} (priority: ${s.getPriority()})`);
+    });
+
+    // Find first strategy that can verify
+    for (const strategy of this.strategies) {
+      if (strategy.canVerify(context)) {
+        console.log(`\n🎯 Selected: ${strategy.getName()}`);
+        return strategy.verify(context);
+      }
+    }
+
+    throw new Error('No verification strategy available for this context');
+  }
+
+  /**
+   * Get strategy by name
+   * @param {string} name - Strategy name
+   * @returns {TestVerificationStrategy|null}
+   */
+  getStrategy(name) {
+    return this.strategies.find(s => s.getName().includes(name)) || null;
+  }
+}
+
+// Export strategy classes for custom implementations
+export { PlaywrightJsonVerificationStrategy } from './playwright-json-strategy.js';
+export { TestVerificationStrategy } from './base.js';
+
+// Export singleton instance
+export const testVerificationManager = new TestVerificationStrategyManager();
+
+export default testVerificationManager;

package/src/runtime/verification/playwright-json-strategy.js

@@ -0,0 +1,119 @@
+/**
+ * Playwright JSON Reporter Verification Strategy
+ * Runs Playwright tests with --reporter=json and parses results
+ */
+import { TestVerificationStrategy } from './base.js';
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+
+export class PlaywrightJsonVerificationStrategy extends TestVerificationStrategy {
+  getName() {
+    return 'Playwright JSON Reporter';
+  }
+
+  getPriority() {
+    return 100; // Default strategy
+  }
+
+  canVerify(context) {
+    const { testFilePath } = context;
+    return existsSync(testFilePath);
+  }
+
+  async verify(context) {
+    const { testFilePath, cwd, timeout = 30000 } = context;
+
+    try {
+      console.log(`🧪 Running test: ${testFilePath}`);
+      
+      const command = `npx playwright test ${testFilePath} --reporter=json --timeout=${timeout}`;
+      
+      const result = execSync(command, {
+        cwd,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: timeout + 10000 // Add 10s buffer for Playwright overhead
+      });
+
+      // Parse Playwright JSON output
+      const json = JSON.parse(result);
+      const stats = json.stats || {};
+
+      return {
+        success: stats.unexpected === 0,
+        passed: stats.expected || 0,
+        failed: stats.unexpected || 0,
+        error: null,
+        errorDetails: null
+      };
+    } catch (error) {
+      // Parse error output for test failure details
+      const output = error.stdout || error.stderr || error.message;
+      
+      try {
+        const json = JSON.parse(output);
+        const stats = json.stats || {};
+        
+        // Extract error message from failed test
+        let errorMsg = 'Test execution failed';
+        if (json.suites && json.suites.length > 0) {
+          const suite = json.suites[0];
+          if (suite.specs && suite.specs.length > 0) {
+            const spec = suite.specs[0];
+            if (spec.tests && spec.tests.length > 0) {
+              const test = spec.tests[0];
+              if (test.results && test.results.length > 0) {
+                const testResult = test.results[0];
+                if (testResult.error) {
+                  errorMsg = testResult.error.message || errorMsg;
+                }
+              }
+            }
+          }
+        }
+
+        // Detect environment/setup errors that shouldn't trigger retries
+        const isEnvironmentError = 
+          errorMsg.includes('Executable doesn\'t exist') ||
+          errorMsg.includes('browserType.launch') ||
+          errorMsg.includes('Please run the following command') ||
+          errorMsg.includes('npx playwright install') ||
+          output.includes('Executable doesn\'t exist') ||
+          output.includes('npx playwright install');
+
+        return {
+          success: false,
+          passed: stats.expected || 0,
+          failed: stats.unexpected || 0,
+          error: errorMsg,
+          errorDetails: errorMsg,
+          isEnvironmentError
+        };
+      } catch (_parseError) {
+        // If JSON parsing fails, extract error from raw output
+        const errorMatch = output.match(/Error: (.+)/);
+        const errorMsg = errorMatch ? errorMatch[1] : 'Test execution failed';
+
+        // Detect environment/setup errors that shouldn't trigger retries
+        const isEnvironmentError = 
+          errorMsg.includes('Executable doesn\'t exist') ||
+          errorMsg.includes('browserType.launch') ||
+          errorMsg.includes('Please run the following command') ||
+          errorMsg.includes('npx playwright install') ||
+          output.includes('Executable doesn\'t exist') ||
+          output.includes('npx playwright install');
+
+        return {
+          success: false,
+          passed: 0,
+          failed: 1,
+          error: errorMsg,
+          errorDetails: errorMsg,
+          isEnvironmentError
+        };
+      }
+    }
+  }
+}
+
+export default PlaywrightJsonVerificationStrategy;

package/src/runtime/zibby-runtime.js

@@ -0,0 +1,299 @@
+/* global document, MutationObserver */
+
+/**
+ * ZibbyRuntime - The "Safe API" for resilient test execution.
+ * Uses DOM similarity scoring and structural context for maximum reliability.
+ */
+export class ZibbyRuntime {
+  static async step(page, fingerprint) {
+    const { name, action, value, strategies, options = { timeout: 10000 }, enrichedData } = fingerprint;
+    
+    console.log(`[Zibby] ⚡ Executing step: ${name}`);
+    
+    // WAIT FOR PAGE STABILITY (network idle + no mutations)
+    await this.waitForPageStability(page, options.timeout);
+    
+    // PARALLEL SEARCH: Try all strategies simultaneously and score results
+    const element = await this.findBestMatch(page, strategies, name);
+    
+    if (!element) {
+      throw new Error(`[Zibby] ❌ Failed to find "${name}" using ${strategies.length} strategies`);
+    }
+
+    // POSITION VERIFICATION (if enriched data available)
+    if (enrichedData?.position) {
+      await this.verifyPosition(element, enrichedData.position);
+    }
+
+    // PERFORM ACTION WITH RETRY
+    await this.performActionWithRetry(page, element, action, value, 3);
+    
+    console.log(`[Zibby] ✨ Step "${name}" completed.`);
+  }
+
+  /**
+   * Wait for page to be stable (network idle + no DOM mutations)
+   */
+  static async waitForPageStability(page, _timeout = 10000) {
+    try {
+      // Wait for network to be idle
+      await page.waitForLoadState('networkidle', { timeout: 3000 }).catch(() => {});
+      
+      // Wait for no DOM mutations for 500ms
+      await page.evaluate(() => {
+        return new Promise((resolve) => {
+          let mutationTimer;
+          const observer = new MutationObserver(() => {
+            clearTimeout(mutationTimer);
+            mutationTimer = setTimeout(() => {
+              observer.disconnect();
+              resolve();
+            }, 500);
+          });
+          
+          observer.observe(document.body, {
+            childList: true,
+            subtree: true,
+            attributes: true
+          });
+          
+          // Start initial timeout
+          mutationTimer = setTimeout(() => {
+            observer.disconnect();
+            resolve();
+          }, 500);
+        });
+      }).catch(() => {});
+    } catch (_e) {
+      // Non-fatal, continue execution
+    }
+  }
+
+  /**
+   * Verify element is at expected position (prevents layout shift issues)
+   */
+  static async verifyPosition(element, expectedPos) {
+    try {
+      const box = await element.boundingBox();
+      if (!box) return; // Element not visible yet
+      
+      const xDiff = Math.abs(box.x - expectedPos.x);
+      const yDiff = Math.abs(box.y - expectedPos.y);
+      
+      // Allow 50px tolerance for responsive layouts
+      if (xDiff > 50 || yDiff > 50) {
+        console.log(`[Zibby] ⚠️  Element moved: expected (${expectedPos.x}, ${expectedPos.y}), got (${box.x}, ${box.y})`);
+        // Wait a bit for layout to stabilize
+        await new Promise(r => setTimeout(r, 500));
+      }
+    } catch (_e) {
+      // Non-fatal
+    }
+  }
+
+  /**
+   * Perform action with automatic retry on failure
+   */
+  static async performActionWithRetry(page, element, action, value, maxRetries = 3) {
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        if (action === 'click') {
+          await element.click();
+        } else if (action === 'fill') {
+          await element.fill(value || '');
+        } else if (action === 'type') {
+          await element.pressSequentially(value || '');
+        } else if (action === 'selectOption') {
+          await element.selectOption(value || '');
+        }
+        return; // Success
+      } catch (e) {
+        if (attempt === maxRetries) throw e; // e is re-thrown, so keep the name
+        
+        console.log(`[Zibby] ⚠️  Action failed (attempt ${attempt}/${maxRetries}), retrying...`);
+        await new Promise(r => setTimeout(r, 1000 * attempt)); // Exponential backoff
+      }
+    }
+  }
+
+  /**
+   * Find best matching element using parallel search + scoring
+   * This is the core "Industrial Method" that makes tests resilient
+   */
+  static async findBestMatch(page, strategies, elementName) {
+    const _timeout = 10000;
+    const _startTime = Date.now();
+    
+    // Collect all candidates from all strategies (PARALLEL)
+    const candidatePromises = strategies.map(async (strategy, idx) => {
+      try {
+        const locator = this.getLocator(page, strategy);
+        
+        // Get all matching elements (not just first)
+        const elements = await locator.all();
+        
+        if (elements.length === 0) return [];
+        
+        // Score each candidate
+        const scored = await Promise.all(
+          elements.map(async (el, elIdx) => {
+            try {
+              const isVisible = await el.isVisible({ timeout: 100 });
+              if (!isVisible) return null;
+              
+              const score = await this.scoreCandidate(el, strategy, page);
+              return { element: el, strategy, score, strategyIdx: idx, elIdx };
+            } catch (_e) {
+              return null;
+            }
+          })
+        );
+        
+        return scored.filter(c => c !== null);
+      } catch (_e) {
+        return [];
+      }
+    });
+    
+    const allCandidates = (await Promise.all(candidatePromises)).flat();
+    
+    if (allCandidates.length === 0) {
+      console.log(`[Zibby] ❌ No visible candidates found for "${elementName}"`);
+      return null;
+    }
+    
+    // Sort by score (highest first)
+    allCandidates.sort((a, b) => b.score - a.score);
+    
+    const best = allCandidates[0];
+    console.log(`[Zibby] ✅ Found element using ${best.strategy.type} (score: ${best.score.toFixed(2)}, ${allCandidates.length} candidates)`);
+    
+    return best.element;
+  }
+
+  /**
+   * Score a candidate element based on multiple factors
+   * Higher score = better match
+   */
+  static async scoreCandidate(element, strategy, _page) {
+    let score = 0;
+    
+    // Base score by strategy type (priority order)
+    const strategyScores = {
+      testid: 120,   // data-testid (most stable)
+      id: 110,       // Stable IDs
+      role: 100,     // Accessibility-first
+      label: 90,
+      class: 85,     // Stable class names
+      placeholder: 85,
+      text: 80,
+      css: 50        // Last resort
+    };
+    score += strategyScores[strategy.type] || 50;
+    
+    // Bonus for high-priority markers
+    if (strategy.priority === 'high') score += 20;
+    if (strategy.priority === 'medium') score += 10;
+    
+    // Penalty for fuzzy text matches
+    if (strategy.fuzzy) score -= 15;
+    
+    // Bonus for structural context (parent/sibling anchors)
+    if (strategy.parent) {
+      try {
+        const parent = element.locator('xpath=ancestor::*').first();
+        const parentMatches = await parent.evaluate((el, selector) => {
+          return el.matches(selector);
+        }, strategy.parent);
+        if (parentMatches) score += 30;
+      } catch {
+        // Ignore parent matching errors
+      }
+    }
+    
+    if (strategy.sibling) {
+      try {
+        const hasSibling = await element.evaluate((el, selector) => {
+          const sibling = el.parentElement?.querySelector(selector);
+          return sibling !== null;
+        }, strategy.sibling);
+        if (hasSibling) score += 20;
+      } catch {
+        // Ignore sibling matching errors
+      }
+    }
+    
+    // Bonus for being in viewport (more likely the target)
+    try {
+      const box = await element.boundingBox();
+      if (box && box.y < 1000) score += 10; // Above fold
+    } catch {
+      // Ignore viewport check errors
+    }
+    
+    // Penalty for nested iframes (usually harder to interact with)
+    try {
+      const frameCount = await element.evaluate(el => {
+        let count = 0;
+        let current = el;
+        while (current) {
+          if (current.tagName === 'IFRAME') count++;
+          current = current.parentElement;
+        }
+        return count;
+      });
+      score -= frameCount * 5;
+    } catch {
+      // Ignore iframe check errors
+    }
+    
+    return score;
+  }
+
+  static getLocator(page, strategy) {
+    let baseLocator;
+    
+    switch (strategy.type) {
+      case 'testid':
+        baseLocator = page.getByTestId(strategy.value);
+        break;
+      case 'id':
+        baseLocator = page.locator(`#${strategy.value}`);
+        break;
+      case 'class':
+        baseLocator = page.locator(`.${strategy.value.replace(/\./g, '.')}`);
+        break;
+      case 'text':
+        if (strategy.fuzzy) {
+          // Fuzzy match - contains text
+          baseLocator = page.getByText(new RegExp(strategy.text, 'i'));
+        } else {
+          // Exact-ish match (Playwright's default)
+          baseLocator = page.getByText(strategy.text, { exact: false });
+        }
+        break;
+      case 'role':
+        baseLocator = page.getByRole(strategy.role, { name: strategy.name, exact: false });
+        break;
+      case 'label':
+        baseLocator = page.getByLabel(strategy.label, { exact: false });
+        break;
+      case 'placeholder':
+        baseLocator = page.getByPlaceholder(strategy.placeholder);
+        break;
+      case 'css':
+      default: {
+        const cleanCss = strategy.value?.replace(/aria-ref=e\d+ >> /g, '') || strategy.css;
+        baseLocator = page.locator(cleanCss);
+        break;
+      }
+    }
+    
+    // Add structural context filters if present
+    if (strategy.parent) {
+      baseLocator = baseLocator.filter({ has: page.locator(strategy.parent) });
+    }
+    
+    return baseLocator;
+  }
+}

package/src/sync/index.js

@@ -0,0 +1,2 @@
+export { ZibbyUploader, createUploader } from './uploader.js';
+

package/src/sync/uploader.js

@@ -0,0 +1,29 @@
+
+/**
+ * Zibby Cloud Uploader (stub)
+ * 
+ * Cloud upload is handled server-side via the Zibby API.
+ * This module provides the client-side interface — actual upload
+ * is done in `cli/src/commands/run.js` via the REST API.
+ */
+
+export class ZibbyUploader {
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey;
+    this.baseUrl = options.baseUrl || process.env.ZIBBY_API_URL || 'https://api-prod.zibby.app';
+    this.enabled = !!apiKey;
+  }
+
+  isEnabled() {
+    return this.enabled;
+  }
+}
+
+/**
+ * Create uploader from environment
+ */
+export function createUploader() {
+  const apiKey = process.env.ZIBBY_API_KEY;
+  return new ZibbyUploader(apiKey);
+}
+

package/src/tools/run-playwright-test.js

@@ -0,0 +1,158 @@
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { dirname, resolve, relative } from 'path';
+
+const executionCounts = new Map();
+const MAX_EXECUTIONS = 8;
+
+export const runPlaywrightTestTool = {
+  name: 'run_playwright_test',
+  description: `Run a Playwright test file and return results. Use this after writing a test to verify it works. If it fails, fix the issues and run again. Maximum ${MAX_EXECUTIONS} attempts per session.`,
+  
+  inputSchema: {
+    type: 'object',
+    properties: {
+      scriptPath: {
+        type: 'string',
+        description: 'Path to the Playwright test file (e.g., tests/login.spec.js)'
+      }
+    },
+    required: ['scriptPath']
+  },
+  
+  async execute({ scriptPath }, context) {
+    const sessionId = context?.sessionId || 'default';
+    const key = `${sessionId}:${scriptPath}`;
+    
+    const count = (executionCounts.get(key) || 0) + 1;
+    executionCounts.set(key, count);
+    
+    if (count > MAX_EXECUTIONS) {
+      return {
+        success: false,
+        executionCount: count,
+        maxReached: true,
+        error: `Maximum ${MAX_EXECUTIONS} executions reached. Stop retrying and return your best result.`
+      };
+    }
+    
+    const projectRoot = context?.projectRoot || process.cwd();
+    const fullPath = resolve(projectRoot, scriptPath);
+    
+    // Prevent path traversal outside project root
+    const rel = relative(projectRoot, fullPath);
+    if (rel.startsWith('..') || resolve(fullPath) !== fullPath && rel.includes('..')) {
+      return {
+        success: false,
+        executionCount: count,
+        error: `Path traversal detected: scriptPath must be within the project root.`
+      };
+    }
+    
+    if (!existsSync(fullPath)) {
+      return {
+        success: false,
+        executionCount: count,
+        error: `Test file not found: ${fullPath}. Make sure you wrote the file first using the write tool.`
+      };
+    }
+    
+    return new Promise((resolvePromise) => {
+      const _testDir = dirname(fullPath);
+      
+      const proc = spawn('npx', ['playwright', 'test', fullPath, '--reporter=line'], {
+        cwd: projectRoot,
+        env: { ...process.env, FORCE_COLOR: '0' }
+      });
+      
+      let stdout = '';
+      let stderr = '';
+      
+      proc.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+      
+      proc.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+      
+      const timeout = setTimeout(() => {
+        proc.kill('SIGTERM');
+        resolvePromise({
+          success: false,
+          executionCount: count,
+          error: 'Test timed out after 60 seconds',
+          stdout: stdout.slice(-2000),
+          stderr: stderr.slice(-1000)
+        });
+      }, 60000);
+      
+      proc.on('close', (code) => {
+        clearTimeout(timeout);
+        
+        const output = `${stdout  }\n${  stderr}`;
+        const lines = output.split('\n');
+        
+        let errorSummary = '';
+        let failedAt = null;
+        
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i];
+          if (line.includes('Error:') || line.includes('error:') || line.includes('✘')) {
+            errorSummary += `${line  }\n`;
+            for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
+              errorSummary += `${lines[j]  }\n`;
+            }
+          }
+          if (line.includes('at ') && line.includes('.spec.')) {
+            const match = line.match(/:(\d+):\d+/);
+            if (match) failedAt = parseInt(match[1]);
+          }
+        }
+        
+        if (code === 0) {
+          resolvePromise({
+            success: true,
+            executionCount: count,
+            message: 'All tests passed!',
+            output: stdout.slice(-500)
+          });
+        } else {
+          resolvePromise({
+            success: false,
+            executionCount: count,
+            remainingAttempts: MAX_EXECUTIONS - count,
+            error: errorSummary.slice(0, 1500) || 'Test failed (see output)',
+            failedAtLine: failedAt,
+            stdout: stdout.slice(-1500),
+            stderr: stderr.slice(-500),
+            hint: count < MAX_EXECUTIONS 
+              ? 'Fix the error and run again.' 
+              : 'Last attempt - make your best fix.'
+          });
+        }
+      });
+      
+      proc.on('error', (err) => {
+        clearTimeout(timeout);
+        resolvePromise({
+          success: false,
+          executionCount: count,
+          error: `Failed to run test: ${err.message}`
+        });
+      });
+    });
+  },
+  
+  resetCount(sessionId) {
+    for (const key of executionCounts.keys()) {
+      if (key.startsWith(`${sessionId  }:`)) {
+        executionCounts.delete(key);
+      }
+    }
+  }
+};
+
+export function resetExecutionCount(sessionId) {
+  runPlaywrightTestTool.resetCount(sessionId);
+}