@matware/e2e-runner 1.2.1 → 1.3.0

package/src/config.js

@@ -12,6 +12,22 @@ import fs from 'fs';
 import path from 'path';
 import { pathToFileURL } from 'url';
 
+/** Deep merge utility for nested config objects */
+function deepMerge(...objects) {
+  const result = {};
+  for (const obj of objects) {
+    if (!obj || typeof obj !== 'object') continue;
+    for (const key of Object.keys(obj)) {
+      if (obj[key] && typeof obj[key] === 'object' && !Array.isArray(obj[key])) {
+        result[key] = deepMerge(result[key] || {}, obj[key]);
+      } else if (obj[key] !== undefined) {
+        result[key] = obj[key];
+      }
+    }
+  }
+  return result;
+}
+
 const DEFAULTS = {
   baseUrl: 'http://host.docker.internal:3000',
   poolUrl: 'ws://localhost:3333',
@@ -51,12 +67,65 @@ const DEFAULTS = {
   neo4jPassword: 'e2erunner',
   neo4jBoltPort: 7687,
   neo4jHttpPort: 7474,
+  verificationStrictness: 'moderate',
+  networkIgnoreDomains: [],
+  authLoginEndpoint: null,
+  authCredentials: null,
+  authTokenPath: 'token',
+  gqlEndpoint: '/api/graphql',
+  gqlAuthHeader: 'Authorization',
+  gqlAuthKey: 'accessToken',
+  gqlAuthPrefix: 'Bearer ',
+  poolUrls: null,
+  watchInterval: null,
+  watchRunOnStart: true,
+  watchGitPoll: false,
+  watchGitBranch: null,
+  watchGitInterval: '30s',
+  watchWebhookUrl: null,
+  watchWebhookEvents: 'failure',
+  watchProjects: null,
+  
+  // Sync configuration
+  sync: {
+    mode: 'standalone',  // 'standalone' | 'hub' | 'agent'
+    hub: {
+      port: null,        // null = use dashboardPort
+      tls: {
+        enabled: false,
+        certPath: null,
+        keyPath: null,
+        mtls: false,
+        caPath: null,
+      },
+      allowRegistration: true,
+      requireApproval: false,
+      masterKeyEnv: 'E2E_SYNC_MASTER_KEY',
+    },
+    agent: {
+      hubUrl: null,
+      instanceId: null,
+      displayName: null,
+      apiKeyEnv: 'E2E_SYNC_API_KEY',
+      totpSecretEnv: 'E2E_SYNC_TOTP',
+      tls: {
+        certPath: null,
+        keyPath: null,
+        caPath: null,
+      },
+      autoSync: true,
+      pullOnDashboard: true,
+      offlineQueue: true,
+      queueRetryInterval: 60,
+    },
+  },
 };
 
 function loadEnvVars() {
   const env = {};
   if (process.env.BASE_URL) env.baseUrl = process.env.BASE_URL;
   if (process.env.CHROME_POOL_URL) env.poolUrl = process.env.CHROME_POOL_URL;
+  if (process.env.CHROME_POOL_URLS) env.poolUrls = process.env.CHROME_POOL_URLS.split(',').map(u => u.trim()).filter(Boolean);
   if (process.env.TESTS_DIR) env.testsDir = process.env.TESTS_DIR;
   if (process.env.MODULES_DIR) env.modulesDir = process.env.MODULES_DIR;
   if (process.env.SCREENSHOTS_DIR) env.screenshotsDir = process.env.SCREENSHOTS_DIR;
@@ -86,6 +155,61 @@ function loadEnvVars() {
   if (process.env.NEO4J_PASSWORD) env.neo4jPassword = process.env.NEO4J_PASSWORD;
   if (process.env.NEO4J_BOLT_PORT) env.neo4jBoltPort = parseInt(process.env.NEO4J_BOLT_PORT);
   if (process.env.NEO4J_HTTP_PORT) env.neo4jHttpPort = parseInt(process.env.NEO4J_HTTP_PORT);
+  if (process.env.NETWORK_IGNORE_DOMAINS) env.networkIgnoreDomains = process.env.NETWORK_IGNORE_DOMAINS.split(',').map(d => d.trim()).filter(Boolean);
+  if (process.env.AUTH_LOGIN_ENDPOINT) env.authLoginEndpoint = process.env.AUTH_LOGIN_ENDPOINT;
+  if (process.env.AUTH_TOKEN_PATH) env.authTokenPath = process.env.AUTH_TOKEN_PATH;
+  if (process.env.GQL_ENDPOINT) env.gqlEndpoint = process.env.GQL_ENDPOINT;
+  if (process.env.GQL_AUTH_HEADER) env.gqlAuthHeader = process.env.GQL_AUTH_HEADER;
+  if (process.env.GQL_AUTH_KEY) env.gqlAuthKey = process.env.GQL_AUTH_KEY;
+  if (process.env.GQL_AUTH_PREFIX) env.gqlAuthPrefix = process.env.GQL_AUTH_PREFIX;
+  if (process.env.WATCH_INTERVAL) env.watchInterval = process.env.WATCH_INTERVAL;
+  if (process.env.WATCH_WEBHOOK_URL) env.watchWebhookUrl = process.env.WATCH_WEBHOOK_URL;
+  if (process.env.WATCH_WEBHOOK_EVENTS) env.watchWebhookEvents = process.env.WATCH_WEBHOOK_EVENTS;
+  if (process.env.WATCH_GIT_POLL) env.watchGitPoll = process.env.WATCH_GIT_POLL === 'true' || process.env.WATCH_GIT_POLL === '1';
+  if (process.env.WATCH_GIT_BRANCH) env.watchGitBranch = process.env.WATCH_GIT_BRANCH;
+  if (process.env.WATCH_GIT_INTERVAL) env.watchGitInterval = process.env.WATCH_GIT_INTERVAL;
+  if (process.env.VERIFICATION_STRICTNESS) {
+    const val = process.env.VERIFICATION_STRICTNESS.toLowerCase();
+    if (['strict', 'moderate', 'lenient'].includes(val)) {
+      env.verificationStrictness = val;
+    }
+  }
+  
+  // Sync configuration from env vars
+  if (process.env.E2E_SYNC_MODE) {
+    const mode = process.env.E2E_SYNC_MODE.toLowerCase();
+    if (['standalone', 'hub', 'agent'].includes(mode)) {
+      env.sync = env.sync || {};
+      env.sync.mode = mode;
+    }
+  }
+  if (process.env.E2E_SYNC_HUB_URL) {
+    env.sync = env.sync || {};
+    env.sync.agent = env.sync.agent || {};
+    env.sync.agent.hubUrl = process.env.E2E_SYNC_HUB_URL;
+  }
+  if (process.env.E2E_SYNC_INSTANCE_ID) {
+    env.sync = env.sync || {};
+    env.sync.agent = env.sync.agent || {};
+    env.sync.agent.instanceId = process.env.E2E_SYNC_INSTANCE_ID;
+  }
+  if (process.env.E2E_SYNC_DISPLAY_NAME) {
+    env.sync = env.sync || {};
+    env.sync.agent = env.sync.agent || {};
+    env.sync.agent.displayName = process.env.E2E_SYNC_DISPLAY_NAME;
+  }
+  if (process.env.E2E_SYNC_HUB_PORT) {
+    env.sync = env.sync || {};
+    env.sync.hub = env.sync.hub || {};
+    env.sync.hub.port = parseInt(process.env.E2E_SYNC_HUB_PORT);
+  }
+  if (process.env.E2E_SYNC_TLS_ENABLED) {
+    env.sync = env.sync || {};
+    env.sync.hub = env.sync.hub || {};
+    env.sync.hub.tls = env.sync.hub.tls || {};
+    env.sync.hub.tls.enabled = process.env.E2E_SYNC_TLS_ENABLED === 'true' || process.env.E2E_SYNC_TLS_ENABLED === '1';
+  }
+  
   return env;
 }
 
@@ -142,6 +266,16 @@ export async function loadConfig(cliArgs = {}, cwd = null) {
     ...envConfig,
     ...cliArgs,
   };
+  
+  // Deep merge sync config (nested objects need special handling)
+  if (fileConfig.sync || envConfig.sync || cliArgs.sync) {
+    config.sync = deepMerge(
+      DEFAULTS.sync,
+      fileConfig.sync || {},
+      envConfig.sync || {},
+      cliArgs.sync || {}
+    );
+  }
 
   // Apply environment profile overrides
   if (config.env && config.env !== 'default' && config.environments?.[config.env]) {
@@ -172,5 +306,14 @@ export async function loadConfig(cliArgs = {}, cwd = null) {
     config.projectName = path.basename(cwd);
   }
 
+  // Normalize pool URLs: poolUrls array → _poolUrls, keep poolUrl as primary
+  if (config.poolUrls && Array.isArray(config.poolUrls) && config.poolUrls.length > 0) {
+    config._poolUrls = config.poolUrls;
+    config.poolUrl = config.poolUrls[0];
+  } else {
+    config._poolUrls = [config.poolUrl];
+  }
+  delete config.poolUrls;
+
   return config;
 }

package/src/dashboard.js

@@ -14,13 +14,15 @@ 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 } from './learner-sqlite.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 +40,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 +94,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 +104,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 +119,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);
         jsonResponse(res, {
-          pool: poolStatus,
+          pool: aggregated,
+          poolUrls,
           dashboard: {
             running: currentRun?.running || false,
             wsClients: wss.clientCount,
@@ -115,8 +131,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 +180,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 +255,56 @@ 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 screenshots list
       const projectScreenshotsMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/screenshots$/);
       if (projectScreenshotsMatch) {
@@ -334,6 +413,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) {
@@ -593,11 +723,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);
+      wss.broadcast(JSON.stringify({ event: 'pool:status', data: aggregated }));
     } catch { /* */ }
   }, 5000);
 
@@ -624,7 +755,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 };
@@ -647,12 +779,12 @@ export async function startDashboard(config) {
         ({ tests, hooks } = loadAllSuites(runConfig.testsDir, runConfig.modulesDir, runConfig.exclude));
       }
 
-      await waitForPool(runConfig.poolUrl);
+      await waitForAnyPool(getPoolUrls(runConfig));
       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 +794,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

@@ -231,6 +231,30 @@ 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');
+  }
+
   // Migrations: add metadata columns to screenshot_hashes
   const ssColumns = db.pragma('table_info(screenshot_hashes)').map(c => c.name);
   if (!ssColumns.includes('test_name')) {
@@ -322,8 +346,8 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy) {
   `);
 
   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)
+    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 (?, ?, ?, ?, ?, ?, ?, ?)');
@@ -382,6 +406,7 @@ 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,
       );
 
       // Register screenshot hashes with metadata
@@ -397,6 +422,9 @@ 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');
+      }
     }
 
     return runDbId;
@@ -405,6 +433,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();
@@ -487,6 +542,7 @@ 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,
       };
     }),
   };
@@ -572,7 +628,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();

package/src/index.js

@@ -9,6 +9,7 @@
 
 export { loadConfig } from './config.js';
 export { waitForPool, connectToPool, startPool, stopPool, restartPool, getPoolStatus } from './pool.js';
+export { getPoolUrls, getAllPoolStatuses, getAggregatedPoolStatus, waitForAnyPool, selectPool, selectAndConnect } from './pool-manager.js';
 export { executeAction } from './actions.js';
 export { runTest, runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites } from './runner.js';
 export { generateReport, generateJUnitXML, saveReport, printReport, saveHistory, loadHistory, loadHistoryRun } from './reporter.js';
@@ -18,13 +19,13 @@ export { buildPrompt, generateTests, hasApiKey } from './ai-generate.js';
 export { verifyIssue } from './verify.js';
 export { resolveTestData, loadModuleRegistry, listModules } from './module-resolver.js';
 export { learnFromRun, categorizeError } from './learner.js';
-export { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights } from './learner-sqlite.js';
+export { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getTestCreationContext, generateImprovements } from './learner-sqlite.js';
 export { generateLearningsMarkdown } from './learner-markdown.js';
 export { writeToGraph, queryGraph, closeNeo4j } from './learner-neo4j.js';
 export { startNeo4j, stopNeo4j, getNeo4jStatus } from './neo4j-pool.js';
 
 import { loadConfig } from './config.js';
-import { waitForPool } from './pool.js';
+import { waitForAnyPool, getPoolUrls } from './pool-manager.js';
 import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites } from './runner.js';
 import { generateReport, saveReport, printReport } from './reporter.js';
 
@@ -41,7 +42,7 @@ export async function createRunner(userConfig = {}) {
 
     /** Runs all test suites from the tests directory */
     async runAll() {
-      await waitForPool(config.poolUrl);
+      await waitForAnyPool(getPoolUrls(config));
       const { tests, hooks } = loadAllSuites(config.testsDir, config.modulesDir, config.exclude);
       const results = await runTestsParallel(tests, config, hooks);
       const report = generateReport(results);
@@ -52,7 +53,7 @@ export async function createRunner(userConfig = {}) {
 
     /** Runs a single suite by name */
     async runSuite(name) {
-      await waitForPool(config.poolUrl);
+      await waitForAnyPool(getPoolUrls(config));
       const { tests, hooks } = loadTestSuite(name, config.testsDir, config.modulesDir);
       const results = await runTestsParallel(tests, config, hooks);
       const report = generateReport(results);
@@ -63,7 +64,7 @@ export async function createRunner(userConfig = {}) {
 
     /** Runs an array of test objects */
     async runTests(tests) {
-      await waitForPool(config.poolUrl);
+      await waitForAnyPool(getPoolUrls(config));
       const results = await runTestsParallel(tests, config);
       const report = generateReport(results);
       saveReport(report, config.screenshotsDir, config);
@@ -73,7 +74,7 @@ export async function createRunner(userConfig = {}) {
 
     /** Runs tests from a JSON file path */
     async runFile(filePath) {
-      await waitForPool(config.poolUrl);
+      await waitForAnyPool(getPoolUrls(config));
       const { tests, hooks } = loadTestFile(filePath, config.modulesDir);
       const results = await runTestsParallel(tests, config, hooks);
       const report = generateReport(results);