@matware/e2e-runner 1.2.1 → 1.3.1

package/src/dashboard.js

@@ -14,13 +14,16 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import { createWebSocketServer } from './websocket.js';
-import { getPoolStatus, waitForPool } from './pool.js';
+import { getPoolUrls, getAggregatedPoolStatus, waitForAnyPool } from './pool-manager.js';
 import { runTestsParallel, loadAllSuites, loadTestSuite, listSuites } from './runner.js';
 import { generateReport, generateJUnitXML, saveReport, persistRun, loadHistory, loadHistoryRun } from './reporter.js';
-import { listProjects as dbListProjects, getProjectRuns as dbGetProjectRuns, getRunDetail as dbGetRunDetail, getAllRuns as dbGetAllRuns, getRunCount as dbGetRunCount, getProjectScreenshotsDir as dbGetProjectScreenshotsDir, getProjectTestsDir as dbGetProjectTestsDir, getProjectCwd as dbGetProjectCwd, lookupScreenshotHash as dbLookupScreenshotHash, ensureProject as dbEnsureProject, getNetworkLogs as dbGetNetworkLogs, closeDb } from './db.js';
+import { listProjects as dbListProjects, listProjectsWithSparklines as dbListProjectsWithSparklines, getProjectRuns as dbGetProjectRuns, getRunDetail as dbGetRunDetail, getAllRuns as dbGetAllRuns, getRunCount as dbGetRunCount, getProjectScreenshotsDir as dbGetProjectScreenshotsDir, getProjectTestsDir as dbGetProjectTestsDir, getProjectCwd as dbGetProjectCwd, lookupScreenshotHash as dbLookupScreenshotHash, ensureProject as dbEnsureProject, getNetworkLogs as dbGetNetworkLogs, listVariables as dbListVariables, setVariable as dbSetVariable, deleteVariable as dbDeleteVariable, closeDb } from './db.js';
 import { loadConfig } from './config.js';
 import { log, colors as C } from './logger.js';
-import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends } from './learner-sqlite.js';
+import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getHealthSnapshot, getActionHealthScores } from './learner-sqlite.js';
+import { compareImages } from './visual-diff.js';
+import { handleSyncRoutes } from './sync/hub-routes.js';
+import { migrateSyncSchema } from './sync/schema.js';
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -38,6 +41,12 @@ export async function startDashboard(config) {
   const port = config.dashboardPort || 8484;
   const MAX_BODY = 1024 * 1024; // 1MB limit for POST bodies
   const dashboardHtml = fs.readFileSync(path.join(__dirname, '..', 'templates', 'dashboard.html'), 'utf-8');
+  
+  // Migrate sync schema if in hub mode
+  if (config.sync?.mode === 'hub') {
+    migrateSyncSchema();
+    log(`${C.cyan}[sync]${C.reset} Hub mode enabled`);
+  }
 
   let currentRun = null; // { running: true, runId, report } or null
   let latestReport = null;
@@ -86,7 +95,7 @@ export async function startDashboard(config) {
     if (origin && allowedOrigins.includes(origin)) {
       res.setHeader('Access-Control-Allow-Origin', origin);
     }
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Accept, Mcp-Session-Id');
 
     if (req.method === 'OPTIONS') {
@@ -96,6 +105,12 @@ export async function startDashboard(config) {
     }
 
     try {
+      // Handle sync routes if in hub mode
+      if (config.sync?.mode === 'hub' && pathname.startsWith('/api/sync')) {
+        const handled = await handleSyncRoutes(req, res, config, pathname);
+        if (handled) return;
+      }
+      
       // Serve dashboard HTML
       if (pathname === '/' || pathname === '/index.html') {
         res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
@@ -105,9 +120,11 @@ export async function startDashboard(config) {
 
       // API: pool status + dashboard state
       if (pathname === '/api/status') {
-        const poolStatus = await getPoolStatus(config.poolUrl);
+        const poolUrls = getPoolUrls(config);
+        const aggregated = await getAggregatedPoolStatus(poolUrls, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
         jsonResponse(res, {
-          pool: poolStatus,
+          pool: aggregated,
+          poolUrls,
           dashboard: {
             running: currentRun?.running || false,
             wsClients: wss.clientCount,
@@ -115,8 +132,10 @@ export async function startDashboard(config) {
           config: {
             baseUrl: config.baseUrl,
             poolUrl: config.poolUrl,
+            poolUrls,
             concurrency: config.concurrency,
             testsDir: config.testsDir,
+            sync: config.sync || { mode: 'standalone' },
           },
         });
         return;
@@ -162,6 +181,17 @@ export async function startDashboard(config) {
         return;
       }
 
+      // API: DB — projects overview with sparklines (Watch view)
+      if (pathname === '/api/db/projects/overview') {
+        try {
+          const limit = parseInt(url.searchParams.get('limit') || '20', 10);
+          jsonResponse(res, dbListProjectsWithSparklines(limit));
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
       // API: DB — runs for a project
       const projectRunsMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/runs$/);
       if (projectRunsMatch) {
@@ -226,6 +256,88 @@ export async function startDashboard(config) {
         return;
       }
 
+      // API: DB — run insights (health + contextual insights)
+      const runInsightsMatch = pathname.match(/^\/api\/db\/runs\/(\d+)\/insights$/);
+      if (runInsightsMatch) {
+        try {
+          const runDbId = parseInt(runInsightsMatch[1], 10);
+          const detail = dbGetRunDetail(runDbId);
+          if (!detail) { jsonResponse(res, { error: 'Run not found' }, 404); return; }
+
+          const projectId = detail.projectId || null;
+          const health = projectId ? getHealthSnapshot(projectId) : null;
+
+          // Build a minimal report object for getRunInsights
+          const results = (detail.results || []).map(r => ({
+            name: r.name,
+            success: r.success,
+            actions: r.actions || [],
+          }));
+          const insights = projectId ? getRunInsights(projectId, { results }) : [];
+
+          jsonResponse(res, { health, insights });
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
+      // API: DB — project health snapshot
+      const projectHealthMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/health$/);
+      if (projectHealthMatch) {
+        try {
+          const projectId = parseInt(projectHealthMatch[1], 10);
+          const health = getHealthSnapshot(projectId);
+          jsonResponse(res, health || {});
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
+      // API: DB — cross-project health snapshot
+      if (pathname === '/api/db/health') {
+        try {
+          const health = getHealthSnapshot(null);
+          jsonResponse(res, health || {});
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
+      // API: DB — project config warnings (Docker hostname detection)
+      const configWarningsMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/config-warnings$/);
+      if (configWarningsMatch) {
+        try {
+          const projectId = parseInt(configWarningsMatch[1], 10);
+          const projectCwd = dbGetProjectCwd(projectId);
+          if (!projectCwd) { jsonResponse(res, { warnings: [] }); return; }
+          const cfg = await loadConfig({}, projectCwd);
+          const warnings = [];
+          const checkDockerHostname = (url, label) => {
+            try {
+              const parsed = new URL(url);
+              if (!parsed.hostname.includes('.') && parsed.hostname !== 'localhost' && parsed.hostname !== '127') {
+                warnings.push({
+                  type: 'docker-hostname',
+                  field: label,
+                  hostname: parsed.hostname,
+                  url,
+                  message: `"${parsed.hostname}" looks like a Docker-internal hostname. The runner will auto-fallback to localhost for auth, but baseUrl requests go through Chrome in Docker (which can resolve it). If tests fail with ENOTFOUND, ensure Chrome pool is on the same Docker network.`,
+                });
+              }
+            } catch {}
+          };
+          if (cfg.baseUrl) checkDockerHostname(cfg.baseUrl, 'baseUrl');
+          if (cfg.authLoginEndpoint) checkDockerHostname(cfg.authLoginEndpoint, 'authLoginEndpoint');
+          jsonResponse(res, { warnings });
+        } catch (error) {
+          jsonResponse(res, { warnings: [], error: error.message });
+        }
+        return;
+      }
+
       // API: DB — project screenshots list
       const projectScreenshotsMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/screenshots$/);
       if (projectScreenshotsMatch) {
@@ -334,6 +446,57 @@ export async function startDashboard(config) {
         return;
       }
 
+      // API: DB — project variables (list)
+      const projectVarsMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/variables$/);
+      if (projectVarsMatch && req.method === 'GET') {
+        try {
+          const projectId = parseInt(projectVarsMatch[1], 10);
+          jsonResponse(res, dbListVariables(projectId));
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
+      // API: DB — project variables (set/upsert)
+      if (projectVarsMatch && req.method === 'PUT') {
+        let body = '';
+        let oversize = false;
+        req.on('data', chunk => { body += chunk; if (body.length > MAX_BODY) { oversize = true; req.destroy(); } });
+        req.on('end', () => {
+          if (oversize) { jsonResponse(res, { error: 'Payload too large' }, 413); return; }
+          try {
+            const projectId = parseInt(projectVarsMatch[1], 10);
+            const { scope, key, value } = JSON.parse(body);
+            if (!key || value === undefined) { jsonResponse(res, { error: 'Missing key or value' }, 400); return; }
+            dbSetVariable(projectId, scope || 'project', key, value);
+            jsonResponse(res, { ok: true });
+          } catch (error) {
+            jsonResponse(res, { error: error.message }, 500);
+          }
+        });
+        return;
+      }
+
+      // API: DB — project variables (delete)
+      const varDeleteMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/variables\/([^/]+)\/([^/]+)$/);
+      if (varDeleteMatch && req.method === 'DELETE') {
+        try {
+          const projectId = parseInt(varDeleteMatch[1], 10);
+          const scope = decodeURIComponent(varDeleteMatch[2]);
+          const key = decodeURIComponent(varDeleteMatch[3]);
+          const deleted = dbDeleteVariable(projectId, scope, key);
+          if (deleted) {
+            jsonResponse(res, { ok: true });
+          } else {
+            jsonResponse(res, { error: 'Variable not found' }, 404);
+          }
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
       // API: DB — project learnings (summary or specific category)
       const learningsMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/learnings(?:\/(\w+))?$/);
       if (learningsMatch) {
@@ -368,6 +531,9 @@ export async function startDashboard(config) {
             case 'trends':
               data = getTestTrends(projectId, days);
               break;
+            case 'actions':
+              data = getActionHealthScores(projectId, days);
+              break;
             default:
               jsonResponse(res, { error: `Unknown learnings category: ${category}` }, 400);
               return;
@@ -379,6 +545,30 @@ export async function startDashboard(config) {
         return;
       }
 
+      // API: visual diff — compare two screenshots on demand
+      if (pathname === '/api/visual-diff') {
+        try {
+          const baseline = url.searchParams.get('baseline');
+          const current = url.searchParams.get('current');
+          const thresholdParam = url.searchParams.get('threshold');
+          if (!baseline || !current) {
+            jsonResponse(res, { error: 'Missing baseline or current parameter' }, 400); return;
+          }
+          if (!fs.existsSync(baseline)) { jsonResponse(res, { error: `Baseline not found: ${baseline}` }, 404); return; }
+          if (!fs.existsSync(current)) { jsonResponse(res, { error: `Current not found: ${current}` }, 404); return; }
+
+          const diffPath = path.join(config.screenshotsDir, `api-diff-${Date.now()}.png`);
+          const result = compareImages(baseline, current, {
+            threshold: thresholdParam ? parseFloat(thresholdParam) : 0.1,
+            diffOutputPath: diffPath,
+          });
+          jsonResponse(res, { ...result, diffImagePath: diffPath });
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
       // API: serve screenshot by hash (e.g. /api/screenshot-hash/a3f2b1c9)
       const ssHashMatch = pathname.match(/^\/api\/screenshot-hash\/([a-f0-9]{8})$/);
       if (ssHashMatch) {
@@ -533,7 +723,9 @@ export async function startDashboard(config) {
           if (oversize) { jsonResponse(res, { error: 'Payload too large' }, 413); return; }
           try {
             const data = JSON.parse(body);
-            bufferLiveEvent(data);
+            if (data.event !== 'test:frame') {
+              bufferLiveEvent(data);
+            }
             wss.broadcast(JSON.stringify(data));
           } catch { /* */ }
           jsonResponse(res, { ok: true });
@@ -581,8 +773,9 @@ export async function startDashboard(config) {
     }
   }, 30000);
 
+  const devOrigins = process.env.NODE_ENV === 'production' ? [] : ['http://localhost:5173', 'http://127.0.0.1:5173'];
   const wss = createWebSocketServer(server, {
-    allowedOrigins: [`http://localhost:${port}`, `http://127.0.0.1:${port}`],
+    allowedOrigins: [`http://localhost:${port}`, `http://127.0.0.1:${port}`, ...devOrigins],
     onConnect(socket) {
       // Replay live state for new/reconnected clients
       for (const rid of Object.keys(liveEventBuffers)) {
@@ -593,11 +786,12 @@ export async function startDashboard(config) {
     },
   });
 
-  // Pool status polling
+  // Pool status polling (aggregated across all pools)
+  const poolUrls = getPoolUrls(config);
   const pollInterval = setInterval(async () => {
     try {
-      const status = await getPoolStatus(config.poolUrl);
-      wss.broadcast(JSON.stringify({ event: 'pool:status', data: status }));
+      const aggregated = await getAggregatedPoolStatus(poolUrls, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
+      wss.broadcast(JSON.stringify({ event: 'pool:status', data: aggregated }));
     } catch { /* */ }
   }, 5000);
 
@@ -624,7 +818,8 @@ export async function startDashboard(config) {
         const projectCwd = dbGetProjectCwd(params.projectId);
         if (!projectCwd) throw new Error('Project not found');
         runConfig = await loadConfig({}, projectCwd);
-        // Inherit pool URL from dashboard config (pool is shared)
+        // Inherit pool URLs from dashboard config (pool is shared)
+        runConfig._poolUrls = getPoolUrls(config);
         runConfig.poolUrl = config.poolUrl;
       } else {
         runConfig = { ...config };
@@ -633,26 +828,30 @@ export async function startDashboard(config) {
       runConfig.triggeredBy = 'dashboard';
       if (params.concurrency) runConfig.concurrency = params.concurrency;
       if (params.baseUrl) runConfig.baseUrl = params.baseUrl;
+      if (params.screencast !== undefined) runConfig.screencast = params.screencast;
 
       // Wire up onProgress to broadcast WS events
       runConfig.onProgress = (data) => {
-        bufferLiveEvent(data);
+        // Don't buffer screencast frames — they're ephemeral and high volume
+        if (data.event !== 'test:frame') {
+          bufferLiveEvent(data);
+        }
         wss.broadcast(JSON.stringify(data));
       };
 
       let tests, hooks;
       if (params.suite) {
-        ({ tests, hooks } = loadTestSuite(params.suite, runConfig.testsDir));
+        ({ tests, hooks } = loadTestSuite(params.suite, runConfig.testsDir, runConfig.modulesDir));
       } else {
         ({ tests, hooks } = loadAllSuites(runConfig.testsDir, runConfig.modulesDir, runConfig.exclude));
       }
 
-      await waitForPool(runConfig.poolUrl);
+      await waitForAnyPool(getPoolUrls(runConfig), 30000, { poolDriver: runConfig.poolDriver, maxSessions: runConfig.maxSessions });
       const results = await runTestsParallel(tests, runConfig, hooks || {});
       const report = generateReport(results);
       const suiteName = params.suite || null;
       saveReport(report, runConfig.screenshotsDir, runConfig);
-      persistRun(report, runConfig, suiteName);
+      await persistRun(report, runConfig, suiteName);
       latestReport = report;
       currentRun = { running: false };
     } catch (error) {
@@ -662,7 +861,7 @@ export async function startDashboard(config) {
   }
 
   return new Promise((resolve, reject) => {
-    const host = config.dashboardHost || '127.0.0.1';
+    const host = config.dashboardHost || process.env.DASHBOARD_HOST || '0.0.0.0';
 
     server.on('error', (err) => {
       if (err.code === 'EADDRINUSE') {

package/src/db.js

@@ -199,6 +199,24 @@ function migrate(db) {
     CREATE INDEX IF NOT EXISTS idx_al_project  ON api_learnings(project_id);
     CREATE INDEX IF NOT EXISTS idx_al_endpoint ON api_learnings(endpoint);
 
+    CREATE TABLE IF NOT EXISTS action_health (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id      INTEGER NOT NULL REFERENCES projects(id),
+      run_id          INTEGER REFERENCES runs(id) ON DELETE CASCADE,
+      test_name       TEXT NOT NULL,
+      action_index    INTEGER NOT NULL,
+      action_type     TEXT NOT NULL,
+      selector        TEXT,
+      success         INTEGER NOT NULL,
+      duration_ms     INTEGER,
+      console_errors_after INTEGER DEFAULT 0,
+      network_errors_after INTEGER DEFAULT 0,
+      page_url        TEXT,
+      created_at      TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_ah_project  ON action_health(project_id);
+    CREATE INDEX IF NOT EXISTS idx_ah_selector ON action_health(selector);
+
     CREATE TABLE IF NOT EXISTS error_patterns (
       id              INTEGER PRIMARY KEY AUTOINCREMENT,
       project_id      INTEGER NOT NULL REFERENCES projects(id),
@@ -231,6 +249,52 @@ function migrate(db) {
     );
   `);
 
+  // ── Variables table ──────────────────────────────────────────────────────────
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS variables (
+      id         INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id INTEGER NOT NULL REFERENCES projects(id),
+      scope      TEXT NOT NULL DEFAULT 'project',
+      key        TEXT NOT NULL,
+      value      TEXT NOT NULL,
+      created_at TEXT DEFAULT (datetime('now')),
+      updated_at TEXT DEFAULT (datetime('now')),
+      UNIQUE(project_id, scope, key)
+    );
+    CREATE INDEX IF NOT EXISTS idx_vars_project ON variables(project_id);
+    CREATE INDEX IF NOT EXISTS idx_vars_scope   ON variables(project_id, scope);
+  `);
+
+  // Add pool_url column for multi-pool tracking
+  try {
+    db.prepare('SELECT pool_url FROM test_results LIMIT 0').run();
+  } catch {
+    db.exec('ALTER TABLE test_results ADD COLUMN pool_url TEXT');
+  }
+
+  // Add pool_driver column to runs for driver visibility
+  try {
+    db.prepare('SELECT pool_driver FROM runs LIMIT 0').run();
+  } catch {
+    db.exec('ALTER TABLE runs ADD COLUMN pool_driver TEXT');
+  }
+
+  // Add visual diff columns to test_results
+  const trCols = db.pragma('table_info(test_results)').map(c => c.name);
+  if (!trCols.includes('baseline_screenshot')) {
+    db.exec('ALTER TABLE test_results ADD COLUMN baseline_screenshot TEXT');
+  }
+  if (!trCols.includes('verification_screenshot')) {
+    db.exec('ALTER TABLE test_results ADD COLUMN verification_screenshot TEXT');
+  }
+  if (!trCols.includes('diff_screenshot')) {
+    db.exec('ALTER TABLE test_results ADD COLUMN diff_screenshot TEXT');
+  }
+  if (!trCols.includes('visual_diff_json')) {
+    db.exec('ALTER TABLE test_results ADD COLUMN visual_diff_json TEXT');
+  }
+
   // Migrations: add metadata columns to screenshot_hashes
   const ssColumns = db.pragma('table_info(screenshot_hashes)').map(c => c.name);
   if (!ssColumns.includes('test_name')) {
@@ -312,18 +376,18 @@ export function getScreenshotHashes(filePaths) {
 }
 
 /** Save a run + its test results in a single transaction. Returns the run's DB id. */
-export function saveRun(projectId, report, runId, suiteName, triggeredBy) {
+export function saveRun(projectId, report, runId, suiteName, triggeredBy, poolDriver) {
   const d = getDb();
   const { summary, results, generatedAt } = report;
 
   const insertRun = d.prepare(`
-    INSERT INTO runs (project_id, run_id, total, passed, failed, pass_rate, duration, generated_at, suite_name, triggered_by)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO runs (project_id, run_id, total, passed, failed, pass_rate, duration, generated_at, suite_name, triggered_by, pool_driver)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
 
   const insertTest = d.prepare(`
-    INSERT INTO test_results (run_id, name, success, error, start_time, end_time, duration_ms, attempt, max_attempts, error_screenshot, console_logs, network_errors, screenshots, network_logs, actions_json)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO test_results (run_id, name, success, error, start_time, end_time, duration_ms, attempt, max_attempts, error_screenshot, console_logs, network_errors, screenshots, network_logs, actions_json, pool_url, baseline_screenshot, verification_screenshot, diff_screenshot, visual_diff_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
 
   const insertHash = d.prepare('INSERT OR IGNORE INTO screenshot_hashes (hash, file_path, project_id, run_id, test_name, step_index, page_url, screenshot_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?)');
@@ -340,6 +404,7 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy) {
       generatedAt,
       suiteName || null,
       triggeredBy || null,
+      poolDriver || null,
     );
     const runDbId = runInfo.lastInsertRowid;
 
@@ -382,6 +447,11 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy) {
         screenshots.length ? JSON.stringify(screenshots) : null,
         r.networkLogs?.length ? JSON.stringify(r.networkLogs) : null,
         actionsCondensed.length ? JSON.stringify(actionsCondensed) : null,
+        r.poolUrl || null,
+        r.baselineScreenshot || null,
+        r.verificationScreenshot || null,
+        r.diffScreenshot || null,
+        r.visualDiff ? JSON.stringify(r.visualDiff) : null,
       );
 
       // Register screenshot hashes with metadata
@@ -397,6 +467,12 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy) {
       if (r.verificationScreenshot) {
         insertHash.run(computeScreenshotHash(r.verificationScreenshot), r.verificationScreenshot, projectId, runDbId, r.name, null, null, 'verification');
       }
+      if (r.baselineScreenshot) {
+        insertHash.run(computeScreenshotHash(r.baselineScreenshot), r.baselineScreenshot, projectId, runDbId, r.name, null, null, 'baseline');
+      }
+      if (r.diffScreenshot) {
+        insertHash.run(computeScreenshotHash(r.diffScreenshot), r.diffScreenshot, projectId, runDbId, r.name, null, null, 'diff');
+      }
     }
 
     return runDbId;
@@ -405,6 +481,33 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy) {
   return tx();
 }
 
+/** Save a run from sync (remote instance). Returns the run's DB id. */
+export function persistRunFromSync({ projectId, runId, total, passed, failed, passRate, duration, generatedAt, suiteName, triggeredBy, syncInstanceId, syncOrigin }) {
+  const d = getDb();
+  
+  const stmt = d.prepare(`
+    INSERT INTO runs (project_id, run_id, total, passed, failed, pass_rate, duration, generated_at, suite_name, triggered_by, sync_instance_id, sync_origin, synced_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+  `);
+  
+  const result = stmt.run(
+    projectId,
+    runId,
+    total,
+    passed,
+    failed,
+    passRate,
+    duration,
+    generatedAt,
+    suiteName || null,
+    triggeredBy || null,
+    syncInstanceId || null,
+    syncOrigin || 'remote'
+  );
+  
+  return result.lastInsertRowid;
+}
+
 /** List all projects with aggregated stats. */
 export function listProjects() {
   const d = getDb();
@@ -425,7 +528,7 @@ export function listProjects() {
 export function getProjectRuns(projectId, limit = 50, offset = 0) {
   const d = getDb();
   return d.prepare(`
-    SELECT id, run_id, total, passed, failed, pass_rate, duration, generated_at, suite_name, triggered_by
+    SELECT id, run_id, total, passed, failed, pass_rate, duration, generated_at, suite_name, triggered_by, pool_driver
     FROM runs
     WHERE project_id = ?
     ORDER BY generated_at DESC
@@ -448,6 +551,9 @@ export function getRunDetail(runDbId) {
     const ss = t.screenshots ? JSON.parse(t.screenshots) : [];
     allPaths.push(...ss);
     if (t.error_screenshot) allPaths.push(t.error_screenshot);
+    if (t.baseline_screenshot) allPaths.push(t.baseline_screenshot);
+    if (t.verification_screenshot) allPaths.push(t.verification_screenshot);
+    if (t.diff_screenshot) allPaths.push(t.diff_screenshot);
   }
   const hashMap = getScreenshotHashes(allPaths);
 
@@ -463,6 +569,7 @@ export function getRunDetail(runDbId) {
     generatedAt: run.generated_at,
     suiteName: run.suite_name,
     triggeredBy: run.triggered_by || null,
+    poolDriver: run.pool_driver || null,
     results: tests.map(t => {
       const screenshots = t.screenshots ? JSON.parse(t.screenshots) : [];
       const testPaths = [...screenshots];
@@ -487,6 +594,11 @@ export function getRunDetail(runDbId) {
         networkLogs: t.network_logs ? JSON.parse(t.network_logs) : [],
         actions: t.actions_json ? JSON.parse(t.actions_json) : [],
         screenshotHashes,
+        poolUrl: t.pool_url || null,
+        baselineScreenshot: t.baseline_screenshot || null,
+        verificationScreenshot: t.verification_screenshot || null,
+        diffScreenshot: t.diff_screenshot || null,
+        visualDiff: t.visual_diff_json ? JSON.parse(t.visual_diff_json) : null,
       };
     }),
   };
@@ -497,7 +609,7 @@ export function getAllRuns(limit = 50, offset = 0) {
   const d = getDb();
   return d.prepare(`
     SELECT r.id, r.run_id, r.total, r.passed, r.failed, r.pass_rate, r.duration,
-           r.generated_at, r.suite_name, r.triggered_by, p.name AS project_name, p.id AS project_id
+           r.generated_at, r.suite_name, r.triggered_by, r.pool_driver, p.name AS project_name, p.id AS project_id
     FROM runs r
     JOIN projects p ON p.id = r.project_id
     ORDER BY r.generated_at DESC
@@ -572,7 +684,79 @@ export function getNetworkLogs(runDbId, filters = {}) {
   return results;
 }
 
+// ── Variables CRUD ────────────────────────────────────────────────────────────
+
+/** Upsert a variable. Scope is 'project' or a suite name. */
+export function setVariable(projectId, scope, key, value) {
+  const d = getDb();
+  d.prepare(`
+    INSERT INTO variables (project_id, scope, key, value, updated_at)
+    VALUES (?, ?, ?, ?, datetime('now'))
+    ON CONFLICT(project_id, scope, key)
+    DO UPDATE SET value = excluded.value, updated_at = datetime('now')
+  `).run(projectId, scope, key, value);
+}
+
+/** Get variables for a specific scope. Returns { key: value } map. */
+export function getVariables(projectId, scope) {
+  const d = getDb();
+  const rows = d.prepare('SELECT key, value FROM variables WHERE project_id = ? AND scope = ?').all(projectId, scope);
+  const map = {};
+  for (const r of rows) map[r.key] = r.value;
+  return map;
+}
+
+/** Delete a variable. Returns true if deleted. */
+export function deleteVariable(projectId, scope, key) {
+  const d = getDb();
+  const info = d.prepare('DELETE FROM variables WHERE project_id = ? AND scope = ? AND key = ?').run(projectId, scope, key);
+  return info.changes > 0;
+}
+
+/** List all variables for a project, grouped by scope. Returns { scope: { key: value } }. */
+export function listVariables(projectId) {
+  const d = getDb();
+  const rows = d.prepare('SELECT scope, key, value FROM variables WHERE project_id = ? ORDER BY scope, key').all(projectId);
+  const grouped = {};
+  for (const r of rows) {
+    if (!grouped[r.scope]) grouped[r.scope] = {};
+    grouped[r.scope][r.key] = r.value;
+  }
+  return grouped;
+}
+
 /** Close the database connection. */
+/** Projects with sparkline data (last N run pass rates, oldest→newest). */
+export function listProjectsWithSparklines(sparklineSize = 20) {
+  const d = getDb();
+  const projects = d.prepare(`
+    SELECT
+      p.id, p.cwd, p.name, p.screenshots_dir, p.tests_dir, p.created_at, p.updated_at,
+      COUNT(r.id)          AS runCount,
+      MAX(r.generated_at)  AS lastRunAt,
+      (SELECT r2.pass_rate FROM runs r2 WHERE r2.project_id = p.id ORDER BY r2.generated_at DESC LIMIT 1) AS lastPassRate
+    FROM projects p
+    LEFT JOIN runs r ON r.project_id = p.id
+    GROUP BY p.id
+    ORDER BY p.updated_at DESC
+  `).all();
+
+  const sparkStmt = d.prepare(`
+    SELECT CAST(pass_rate AS REAL) AS rate
+    FROM runs
+    WHERE project_id = ?
+    ORDER BY generated_at DESC
+    LIMIT ?
+  `);
+
+  return projects.map(p => {
+    const rawRates = sparkStmt.all(p.id, sparklineSize).map(r => r.rate);
+    // Reverse to oldest→newest
+    rawRates.reverse();
+    return { ...p, sparkline: rawRates };
+  });
+}
+
 export function closeDb() {
   if (db) {
     db.close();