@matware/e2e-runner 1.2.1 → 1.3.1

package/bin/cli.js

@@ -14,6 +14,8 @@
  *   e2e-runner pool status                Show pool status
  *   e2e-runner pool restart               Restart the pool
  *   e2e-runner dashboard                   Start the web dashboard
+ *   e2e-runner watch --interval 15m       Watch mode: scheduled test runs
+ *   e2e-runner watch --git                Watch mode: run on git changes
  *   e2e-runner capture <url>              Capture a screenshot of any URL
  *   e2e-runner issue <url>                Fetch issue and show details
  *   e2e-runner issue <url> --generate     Generate test file via Claude API
@@ -29,10 +31,12 @@ import path from 'path';
 import http from 'http';
 import { fileURLToPath } from 'url';
 import { loadConfig } from '../src/config.js';
-import { startPool, stopPool, restartPool, getPoolStatus, waitForPool, connectToPool } from '../src/pool.js';
+import { startPool, stopPool, restartPool, connectToPool } from '../src/pool.js';
+import { getPoolUrls, getAggregatedPoolStatus, waitForAnyPool, selectPool } from '../src/pool-manager.js';
 import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites } from '../src/runner.js';
-import { generateReport, saveReport, printReport, persistRun } from '../src/reporter.js';
+import { generateReport, saveReport, printReport, persistRun, printInsights } from '../src/reporter.js';
 import { startDashboard } from '../src/dashboard.js';
+import { startWatch } from '../src/watch.js';
 import { fetchIssue } from '../src/issues.js';
 import { buildPrompt, generateTests, hasApiKey } from '../src/ai-generate.js';
 import { verifyIssue } from '../src/verify.js';
@@ -41,6 +45,22 @@ import { log, colors as C } from '../src/logger.js';
 import { listModules } from '../src/module-resolver.js';
 import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends } from '../src/learner-sqlite.js';
 import { startNeo4j, stopNeo4j, getNeo4jStatus } from '../src/neo4j-pool.js';
+import { 
+  generateApiKey, 
+  generateTotpSecret, 
+  generateTotpUri, 
+  generateMasterKey,
+  hashApiKey,
+  migrateSyncSchema,
+  createInstance,
+  getInstance,
+  listInstances,
+  updateInstanceStatus,
+  getHubConnection,
+  getQueueStats,
+  getSyncClient,
+  pullRuns,
+} from '../src/sync/index.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -63,6 +83,7 @@ function parseCLIConfig() {
   const cliArgs = {};
   if (getFlag('--base-url')) cliArgs.baseUrl = getFlag('--base-url');
   if (getFlag('--pool-url')) cliArgs.poolUrl = getFlag('--pool-url');
+  if (getFlag('--pool-urls')) cliArgs.poolUrls = getFlag('--pool-urls').split(',').map(u => u.trim()).filter(Boolean);
   if (getFlag('--tests-dir')) cliArgs.testsDir = getFlag('--tests-dir');
   if (getFlag('--modules-dir')) cliArgs.modulesDir = getFlag('--modules-dir');
   if (getFlag('--screenshots-dir')) cliArgs.screenshotsDir = getFlag('--screenshots-dir');
@@ -84,6 +105,19 @@ function parseCLIConfig() {
   if (getFlag('--auth-token')) cliArgs.authToken = getFlag('--auth-token');
   if (getFlag('--auth-storage-key')) cliArgs.authStorageKey = getFlag('--auth-storage-key');
   if (getFlag('--test-type')) cliArgs.testType = getFlag('--test-type');
+  if (getFlag('--network-ignore-domains')) cliArgs.networkIgnoreDomains = getFlag('--network-ignore-domains').split(',').map(d => d.trim()).filter(Boolean);
+  if (getFlag('--auth-login-endpoint')) cliArgs.authLoginEndpoint = getFlag('--auth-login-endpoint');
+  if (getFlag('--auth-token-path')) cliArgs.authTokenPath = getFlag('--auth-token-path');
+  if (getFlag('--gql-endpoint')) cliArgs.gqlEndpoint = getFlag('--gql-endpoint');
+  if (getFlag('--gql-auth-header')) cliArgs.gqlAuthHeader = getFlag('--gql-auth-header');
+  if (getFlag('--gql-auth-key')) cliArgs.gqlAuthKey = getFlag('--gql-auth-key');
+  if (getFlag('--gql-auth-prefix')) cliArgs.gqlAuthPrefix = getFlag('--gql-auth-prefix');
+  if (getFlag('--verification-strictness')) {
+    const val = getFlag('--verification-strictness');
+    if (['strict', 'moderate', 'lenient'].includes(val)) {
+      cliArgs.verificationStrictness = val;
+    }
+  }
   return cliArgs;
 }
 
@@ -103,6 +137,12 @@ ${C.bold}Usage:${C.reset}
   e2e-runner dashboard                  Start the web dashboard
   e2e-runner dashboard --port <port>    Custom port (default: 8484)
 
+  e2e-runner watch --interval 15m       Watch mode: run tests on schedule
+  e2e-runner watch --git                Watch mode: run on git changes
+  e2e-runner watch --interval 15m --git Both triggers
+  e2e-runner watch --webhook <url>      Notify on failure/recovery
+  e2e-runner watch --projects <file>    Multi-project watch
+
   e2e-runner capture <url>               Capture a screenshot of any URL
   e2e-runner capture <url> --full-page  Capture full scrollable page
   e2e-runner capture <url> --selector <sel>  Wait for selector before capture
@@ -127,11 +167,20 @@ ${C.bold}Usage:${C.reset}
   e2e-runner neo4j stop                 Stop the Neo4j container
   e2e-runner neo4j status               Show Neo4j status
 
+  e2e-runner sync status                Show sync connection status
+  e2e-runner sync add-instance          Register new agent (hub mode)
+  e2e-runner sync list-instances        List registered agents (hub mode)
+  e2e-runner sync approve <id>          Approve pending agent (hub mode)
+  e2e-runner sync revoke <id>           Suspend an agent (hub mode)
+  e2e-runner sync push                  Process sync queue (agent mode)
+  e2e-runner sync pull                  Pull runs from hub (agent mode)
+
   e2e-runner init                       Scaffold e2e/ in the current project
 
 ${C.bold}Options:${C.reset}
   --base-url <url>         App base URL (default: http://host.docker.internal:3000)
   --pool-url <ws-url>      Chrome Pool URL (default: ws://localhost:3333)
+  --pool-urls <urls>       Multiple Chrome Pool URLs, comma-separated (distributes tests)
   --tests-dir <dir>        Tests directory (default: e2e/tests)
   --modules-dir <dir>      Reusable modules directory (default: e2e/modules)
   --screenshots-dir <dir>  Screenshots directory (default: e2e/screenshots)
@@ -146,6 +195,20 @@ ${C.bold}Options:${C.reset}
   --env <name>             Environment profile from config (default: default)
   --project-name <name>    Project display name for dashboard (default: directory name)
   --fail-on-network-error  Fail tests when network requests fail (e.g. ERR_CONNECTION_REFUSED)
+  --network-ignore-domains <d1,d2>  Ignore network errors from these domains (comma-separated)
+  --auth-login-endpoint <url>  Auto-login: POST credentials to this URL to get auth token
+  --auth-token-path <path>     Dot-path to token in auth response (default: token)
+  --verification-strictness <level>  Visual verification: strict, moderate (default), lenient
+
+${C.bold}Watch Options:${C.reset}
+  --interval <time>          Run interval: 15m, 1h, 30s (required for schedule mode)
+  --git                      Poll git for new commits
+  --git-branch <branch>      Branch to watch (default: HEAD)
+  --git-interval <time>      Git poll frequency (default: 30s)
+  --webhook <url>            Webhook URL for notifications
+  --webhook-events <events>  When to notify: failure (default), recovery, always
+  --projects <file.json>     Multi-project config file
+  --no-run-on-start          Skip initial run on startup
 
 ${C.bold}Config:${C.reset}
   Looks for e2e.config.js or e2e.config.json in the current directory.
@@ -160,8 +223,10 @@ async function cmdRun() {
   let tests = [];
   let hooks = {};
 
+  const poolUrls = getPoolUrls(config);
   console.log(`\n${C.bold}${C.cyan}@matware/e2e-runner${C.reset} v${pkg.version}`);
-  console.log(`${C.dim}Pool: ${config.poolUrl} | Base: ${config.baseUrl} | Concurrency: ${config.concurrency}${C.reset}\n`);
+  const poolDisplay = poolUrls.length > 1 ? `${poolUrls.length} pools` : config.poolUrl;
+  console.log(`${C.dim}Pool: ${poolDisplay} | Base: ${config.baseUrl} | Concurrency: ${config.concurrency}${C.reset}\n`);
 
   if (hasFlag('--all')) {
     const loaded = loadAllSuites(config.testsDir, config.modulesDir, config.exclude);
@@ -198,8 +263,8 @@ async function cmdRun() {
   }
 
   // Verify pool connectivity
-  log('🔌', 'Checking Chrome Pool...');
-  const pressure = await waitForPool(config.poolUrl);
+  log('🔌', `Checking Chrome Pool${poolUrls.length > 1 ? 's' : ''}...`);
+  const pressure = await waitForAnyPool(poolUrls, 30000, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
   log('✅', `Pool ready (${pressure.running}/${pressure.maxConcurrent} sessions, queued: ${pressure.queued})`);
 
   // Wire up live progress to dashboard if running
@@ -222,12 +287,17 @@ async function cmdRun() {
 
   // Execute tests
   console.log('');
-  const suiteName = getFlag('--suite') || (hasFlag('--all') ? null : null);
+  // Derive suite name: --suite flag > --tests file basename > null (for --all/--inline)
+  let suiteName = getFlag('--suite') || null;
+  if (!suiteName && getFlag('--tests')) {
+    suiteName = path.basename(getFlag('--tests'), '.json');
+  }
   const results = await runTestsParallel(tests, config, hooks);
   const report = generateReport(results);
   saveReport(report, config.screenshotsDir, config);
-  persistRun(report, config, suiteName);
+  await persistRun(report, config, suiteName);
   printReport(report, config.screenshotsDir);
+  printInsights(report, config);
 
   // Wait for the last dashboard broadcast (run:complete) to flush before exiting
   if (_lastBroadcast) await _lastBroadcast;
@@ -280,15 +350,32 @@ async function cmdPool() {
       break;
 
     case 'status': {
-      const status = await getPoolStatus(config.poolUrl);
+      const statusPoolUrls = getPoolUrls(config);
+      const aggregated = await getAggregatedPoolStatus(statusPoolUrls, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
       console.log(`\n${C.bold}Chrome Pool Status:${C.reset}\n`);
-      if (status.error) {
-        console.log(`  ${C.red}Offline${C.reset}: ${status.error}`);
+
+      if (statusPoolUrls.length > 1) {
+        console.log(`  Pools:      ${aggregated.totalPools} (${aggregated.availableCount} available)`);
+        console.log(`  Running:    ${aggregated.totalRunning}/${aggregated.totalMaxConcurrent}`);
+        console.log(`  Queued:     ${aggregated.totalQueued}`);
+        console.log('');
+        for (const pool of aggregated.pools) {
+          const label = pool.available ? `${C.green}Available${C.reset}` : pool.error ? `${C.red}Offline${C.reset}` : `${C.red}Busy${C.reset}`;
+          console.log(`  ${C.cyan}${pool.url}${C.reset}`);
+          console.log(`    Status:   ${label}${pool.error ? ` (${pool.error})` : ''}`);
+          console.log(`    Running:  ${pool.running}/${pool.maxConcurrent}`);
+          console.log(`    Queued:   ${pool.queued}`);
+        }
       } else {
-        console.log(`  Status:     ${status.available ? `${C.green}Available${C.reset}` : `${C.red}Busy${C.reset}`}`);
-        console.log(`  Running:    ${status.running}/${status.maxConcurrent}`);
-        console.log(`  Queued:     ${status.queued}`);
-        console.log(`  Sessions:   ${status.sessions.length}`);
+        const pool = aggregated.pools[0];
+        if (pool.error) {
+          console.log(`  ${C.red}Offline${C.reset}: ${pool.error}`);
+        } else {
+          console.log(`  Status:     ${pool.available ? `${C.green}Available${C.reset}` : `${C.red}Busy${C.reset}`}`);
+          console.log(`  Running:    ${pool.running}/${pool.maxConcurrent}`);
+          console.log(`  Queued:     ${pool.queued}`);
+          console.log(`  Sessions:   ${pool.sessions?.length ?? 0}`);
+        }
       }
       console.log('');
       break;
@@ -405,12 +492,15 @@ async function cmdCapture() {
 
   console.log(`\n${C.bold}${C.cyan}@matware/e2e-runner${C.reset} v${pkg.version}`);
 
+  const capturePoolUrls = getPoolUrls(config);
   log('🔌', 'Checking Chrome Pool...');
-  await waitForPool(config.poolUrl);
+  const captureDriverOpts = { poolDriver: config.poolDriver, maxSessions: config.maxSessions };
+  await waitForAnyPool(capturePoolUrls, 30000, captureDriverOpts);
 
   let browser;
   try {
-    browser = await connectToPool(config.poolUrl);
+    const capturePool = await selectPool(capturePoolUrls, 2000, 60000, captureDriverOpts);
+    browser = await connectToPool(capturePool);
     const page = await browser.newPage();
     await page.setViewport(config.viewport);
 
@@ -547,6 +637,46 @@ async function cmdIssue() {
   console.log('');
 }
 
+async function cmdWatch() {
+  const cliArgs = parseCLIConfig();
+
+  // Parse watch-specific flags
+  if (getFlag('--interval')) cliArgs.watchInterval = getFlag('--interval');
+  if (getFlag('--webhook')) cliArgs.watchWebhookUrl = getFlag('--webhook');
+  if (getFlag('--webhook-events')) cliArgs.watchWebhookEvents = getFlag('--webhook-events');
+  if (hasFlag('--git')) cliArgs.watchGitPoll = true;
+  if (getFlag('--git-branch')) cliArgs.watchGitBranch = getFlag('--git-branch');
+  if (getFlag('--git-interval')) cliArgs.watchGitInterval = getFlag('--git-interval');
+  if (hasFlag('--no-run-on-start')) cliArgs.watchRunOnStart = false;
+
+  // Multi-project file
+  const projectsFile = getFlag('--projects');
+  if (projectsFile) {
+    const resolved = path.resolve(projectsFile);
+    if (!fs.existsSync(resolved)) {
+      console.error(`${C.red}Projects file not found: ${resolved}${C.reset}`);
+      process.exit(1);
+    }
+    cliArgs.watchProjects = JSON.parse(fs.readFileSync(resolved, 'utf-8'));
+  }
+
+  const config = await loadConfig(cliArgs);
+
+  console.log(`\n${C.bold}${C.cyan}@matware/e2e-runner${C.reset} v${pkg.version}`);
+  console.log(`${C.dim}Watch mode — dashboard on port ${config.dashboardPort}${C.reset}\n`);
+
+  const handle = await startWatch(config);
+
+  // Graceful shutdown
+  const shutdown = () => {
+    console.log(`\n${C.dim}Stopping watch...${C.reset}`);
+    handle.stop();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
 async function cmdLearnings() {
   const cliArgs = parseCLIConfig();
   const config = await loadConfig(cliArgs);
@@ -696,6 +826,261 @@ async function cmdNeo4j() {
   }
 }
 
+// ==================== Sync ====================
+
+async function cmdSync() {
+  const subCmd = args[1];
+  const cliArgs = parseCLIConfig();
+  const config = await loadConfig(cliArgs);
+  
+  // Ensure schema is migrated
+  migrateSyncSchema();
+
+  switch (subCmd) {
+    case 'status': {
+      const mode = config.sync?.mode || 'standalone';
+      console.log(`\n${C.bold}Sync Status:${C.reset}\n`);
+      console.log(`  Mode:     ${C.cyan}${mode}${C.reset}`);
+      
+      if (mode === 'hub') {
+        const instances = listInstances();
+        const active = instances.filter(i => i.status === 'active').length;
+        const online = instances.filter(i => {
+          if (!i.last_seen) return false;
+          const lastSeen = new Date(i.last_seen + 'Z').getTime();
+          return Date.now() - lastSeen < 5 * 60 * 1000;
+        }).length;
+        console.log(`  Instances: ${instances.length} total, ${active} active, ${online} online`);
+      } else if (mode === 'agent') {
+        const conn = getHubConnection();
+        if (conn) {
+          console.log(`  Hub URL:   ${C.cyan}${conn.hub_url}${C.reset}`);
+          console.log(`  Instance:  ${conn.instance_id}`);
+          console.log(`  Status:    ${conn.status === 'connected' ? C.green : C.red}${conn.status}${C.reset}`);
+          console.log(`  Last push: ${conn.last_push || 'never'}`);
+          console.log(`  Last pull: ${conn.last_pull || 'never'}`);
+        } else {
+          console.log(`  ${C.dim}Not connected to any hub${C.reset}`);
+        }
+        
+        const queueStats = getQueueStats();
+        if (queueStats.length > 0) {
+          const pending = queueStats.find(s => s.status === 'pending')?.count || 0;
+          if (pending > 0) {
+            console.log(`  Queue:     ${C.yellow}${pending} pending${C.reset}`);
+          }
+        }
+      }
+      console.log('');
+      break;
+    }
+    
+    case 'add-instance': {
+      if (config.sync?.mode !== 'hub') {
+        console.error(`${C.red}Error: This command only works in hub mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const instanceId = getFlag('--id') || `instance-${Date.now().toString(36)}`;
+      const displayName = getFlag('--name') || instanceId;
+      const role = getFlag('--role') || 'member';
+      const environment = getFlag('--env') || 'development';
+      
+      // Check if already exists
+      if (getInstance(instanceId)) {
+        console.error(`${C.red}Error: Instance '${instanceId}' already exists${C.reset}`);
+        process.exit(1);
+      }
+      
+      // Generate credentials
+      const apiKey = generateApiKey();
+      const totpSecret = generateTotpSecret();
+      
+      // Create instance
+      createInstance({
+        instanceId,
+        displayName,
+        hostname: null,
+        environment,
+        apiKeyHash: hashApiKey(apiKey),
+        totpSecret,
+        role,
+        status: config.sync?.hub?.requireApproval ? 'pending' : 'active',
+      });
+      
+      console.log(`\n${C.green}${C.bold}Instance created successfully!${C.reset}\n`);
+      console.log(`${C.bold}Instance ID:${C.reset}    ${instanceId}`);
+      console.log(`${C.bold}Display Name:${C.reset}   ${displayName}`);
+      console.log(`${C.bold}Role:${C.reset}           ${role}`);
+      console.log(`${C.bold}Status:${C.reset}         ${config.sync?.hub?.requireApproval ? 'pending' : 'active'}`);
+      console.log('');
+      console.log(`${C.bold}${C.yellow}SAVE THESE CREDENTIALS (shown only once):${C.reset}`);
+      console.log(`${C.bold}API Key:${C.reset}        ${apiKey}`);
+      console.log(`${C.bold}TOTP Secret:${C.reset}    ${totpSecret}`);
+      console.log(`${C.bold}TOTP URI:${C.reset}       ${generateTotpUri(totpSecret, instanceId)}`);
+      console.log('');
+      console.log(`${C.dim}Configure the agent with:${C.reset}`);
+      console.log(`  export E2E_SYNC_API_KEY="${apiKey}"`);
+      console.log(`  export E2E_SYNC_TOTP="${totpSecret}"`);
+      console.log('');
+      break;
+    }
+    
+    case 'list-instances': {
+      if (config.sync?.mode !== 'hub') {
+        console.error(`${C.red}Error: This command only works in hub mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const status = getFlag('--status');
+      const instances = listInstances(status);
+      
+      console.log(`\n${C.bold}Registered Instances:${C.reset}\n`);
+      
+      if (instances.length === 0) {
+        console.log(`  ${C.dim}No instances registered${C.reset}`);
+      } else {
+        for (const inst of instances) {
+          const isOnline = inst.last_seen && (Date.now() - new Date(inst.last_seen + 'Z').getTime() < 5 * 60 * 1000);
+          const statusColor = inst.status === 'active' ? C.green : inst.status === 'pending' ? C.yellow : C.red;
+          const onlineIndicator = isOnline ? `${C.green}*${C.reset}` : ' ';
+          
+          console.log(`  ${onlineIndicator} ${C.bold}${inst.instance_id}${C.reset}`);
+          console.log(`      Name:   ${inst.display_name}`);
+          console.log(`      Status: ${statusColor}${inst.status}${C.reset}`);
+          console.log(`      Role:   ${inst.role}`);
+          console.log(`      Seen:   ${inst.last_seen || 'never'}`);
+          console.log('');
+        }
+      }
+      break;
+    }
+    
+    case 'approve': {
+      if (config.sync?.mode !== 'hub') {
+        console.error(`${C.red}Error: This command only works in hub mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const instanceId = args[2];
+      if (!instanceId) {
+        console.error(`${C.red}Error: Instance ID required${C.reset}`);
+        process.exit(1);
+      }
+      
+      const instance = getInstance(instanceId);
+      if (!instance) {
+        console.error(`${C.red}Error: Instance '${instanceId}' not found${C.reset}`);
+        process.exit(1);
+      }
+      
+      updateInstanceStatus(instanceId, 'active');
+      console.log(`${C.green}Instance '${instanceId}' approved and activated${C.reset}`);
+      break;
+    }
+    
+    case 'revoke': {
+      if (config.sync?.mode !== 'hub') {
+        console.error(`${C.red}Error: This command only works in hub mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const instanceId = args[2];
+      if (!instanceId) {
+        console.error(`${C.red}Error: Instance ID required${C.reset}`);
+        process.exit(1);
+      }
+      
+      updateInstanceStatus(instanceId, 'suspended');
+      console.log(`${C.yellow}Instance '${instanceId}' suspended${C.reset}`);
+      break;
+    }
+    
+    case 'push': {
+      if (config.sync?.mode !== 'agent') {
+        console.error(`${C.red}Error: This command only works in agent mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const client = await getSyncClient(config);
+      if (!client.isConfigured()) {
+        console.error(`${C.red}Error: Sync credentials not configured${C.reset}`);
+        console.log(`${C.dim}Set E2E_SYNC_API_KEY and E2E_SYNC_TOTP environment variables${C.reset}`);
+        process.exit(1);
+      }
+      
+      console.log('Processing sync queue...');
+      await client.processQueue();
+      console.log(`${C.green}Queue processed${C.reset}`);
+      break;
+    }
+    
+    case 'pull': {
+      if (config.sync?.mode !== 'agent') {
+        console.error(`${C.red}Error: This command only works in agent mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const since = getFlag('--since');
+      const project = getFlag('--project');
+      const limit = getFlag('--limit') ? parseInt(getFlag('--limit')) : 50;
+      
+      console.log('Pulling runs from hub...');
+      const result = await pullRuns(config, { since, project, limit });
+      
+      if (result) {
+        console.log(`${C.green}Pulled ${result.runs?.length || 0} runs${C.reset}`);
+        
+        if (result.runs?.length > 0) {
+          console.log('');
+          for (const run of result.runs.slice(0, 10)) {
+            const status = run.failed > 0 ? C.red + 'FAIL' : C.green + 'PASS';
+            console.log(`  ${status}${C.reset} ${run.project_name} - ${run.suite_name || 'default'} (${run.passed}/${run.total})`);
+          }
+          if (result.runs.length > 10) {
+            console.log(`  ${C.dim}... and ${result.runs.length - 10} more${C.reset}`);
+          }
+        }
+      } else {
+        console.log(`${C.yellow}No runs pulled (check configuration)${C.reset}`);
+      }
+      break;
+    }
+    
+    case 'generate-master-key': {
+      const key = generateMasterKey();
+      console.log(`\n${C.bold}Generated Master Key:${C.reset}\n`);
+      console.log(`  ${key}`);
+      console.log('');
+      console.log(`${C.dim}Set this in your hub environment:${C.reset}`);
+      console.log(`  export E2E_SYNC_MASTER_KEY="${key}"`);
+      console.log('');
+      break;
+    }
+    
+    default:
+      console.log(`\n${C.bold}Sync Commands:${C.reset}\n`);
+      console.log('  status              Show sync status');
+      console.log('  add-instance        Register a new agent (hub mode)');
+      console.log('  list-instances      List registered agents (hub mode)');
+      console.log('  approve <id>        Approve pending agent (hub mode)');
+      console.log('  revoke <id>         Suspend an agent (hub mode)');
+      console.log('  push                Process sync queue (agent mode)');
+      console.log('  pull                Pull runs from hub (agent mode)');
+      console.log('  generate-master-key Generate encryption master key');
+      console.log('');
+      console.log(`${C.bold}Options:${C.reset}`);
+      console.log('  --id <id>           Instance ID for add-instance');
+      console.log('  --name <name>       Display name for add-instance');
+      console.log('  --role <role>       Role: admin, member, readonly');
+      console.log('  --status <status>   Filter by status: pending, active, suspended');
+      console.log('  --since <datetime>  Pull runs since timestamp');
+      console.log('  --project <slug>    Filter by project');
+      console.log('  --limit <n>         Limit number of runs to pull');
+      console.log('');
+  }
+}
+
 // ==================== Main ====================
 
 async function main() {
@@ -728,6 +1113,10 @@ async function main() {
       await cmdDashboard();
       break;
 
+    case 'watch':
+      await cmdWatch();
+      break;
+
     case 'capture':
       await cmdCapture();
       break;
@@ -744,6 +1133,10 @@ async function main() {
       await cmdNeo4j();
       break;
 
+    case 'sync':
+      await cmdSync();
+      break;
+
     case 'init':
       cmdInit();
       break;

package/commands/capture.md

@@ -0,0 +1,45 @@
+---
+description: Capture a screenshot of any URL with automatic authentication
+user_invocable: true
+allowed_tools:
+  - mcp__e2e-runner__e2e_pool_status
+  - mcp__e2e-runner__e2e_capture
+  - mcp__e2e-runner__e2e_analyze
+  - mcp__e2e-runner__e2e_screenshot
+---
+
+# Quick Capture
+
+Take a screenshot of any URL in one step. Handles pool checks and authentication automatically.
+
+## Workflow
+
+1. **Check pool** — Call `e2e_pool_status` to confirm the Chrome pool is running. If not available, tell the user to run `npx e2e-runner pool start` via CLI and stop.
+
+2. **Capture** — Call `e2e_capture` with:
+   - `url`: The URL from the user's request (REQUIRED)
+   - `cwd`: The current working directory (REQUIRED — always pass this)
+   - `fullPage`: true if user says "full page", "full", "complete", or "toda la página"
+   - `selector`: CSS selector if user wants to wait for a specific element
+   - `delay`: milliseconds if user says "wait", "delay", or "espera"
+   - `waitUntil`: "domcontentloaded" if user mentions WebSocket, SSE, or real-time apps
+   - `filename`: if user specifies a name
+
+   **Authentication is automatic**: the tool reads `authToken`, `authLoginEndpoint`, and `authCredentials` from the project's `e2e.config.js`. You do NOT need to pass `authToken` unless the user explicitly provides one.
+
+3. **Show result** — The tool returns the screenshot as an inline image. Show it to the user with the file path.
+
+## Arguments
+
+The user passes the URL after the command:
+- `/e2e-runner:capture http://localhost:3000/dashboard` → capture that URL
+- `/e2e-runner:capture http://localhost/concept-maps --full-page` → full page capture
+- `/e2e-runner:capture http://localhost/admin --delay 3000` → wait 3s before capture
+
+If no URL is provided, ask the user for one.
+
+## Important
+
+- Do NOT try to manually authenticate, fetch tokens, write test files, or use curl. The tool handles auth automatically from project config.
+- Do NOT use the `e2e_run` tool — this is a screenshot capture, not a test run.
+- Keep it simple: one `e2e_pool_status` call + one `e2e_capture` call. That's it.

package/commands/create-test.md

@@ -37,11 +37,26 @@ Help the user create a new E2E test file by exploring the application and design
    - Add `wait` actions before assertions on dynamic content
    - Add `assert_no_network_errors` after critical page loads
    - Consider adding an `expect` field for visual verification
+   - **DRY**: If auth/setup is repeated across tests, use `beforeEach` hook (object format) instead of repeating per test
+   - **DRY**: If 3+ tests repeat the same action pattern, create a module with `e2e_create_module` first
 
-7. **Create the test** — Call `e2e_create_test` with the designed test structure. Consider creating reusable modules with `e2e_create_module` for repeated sequences (auth, navigation).
+7. **Create the test** — Call `e2e_create_test` with the designed test structure.
+   - Check existing modules (`e2e/modules/`) — reuse them via `$use` instead of duplicating actions
+   - Create new modules with `e2e_create_module` for repeated sequences (auth, navigation, screenshot patterns)
+   - Use object format `{ "beforeEach": [...], "tests": [...] }` when hooks are needed
 
 8. **Validate** — Run the newly created test with `e2e_run` using the `suite` parameter. Analyze results and iterate if needed.
 
+## Naming Rules (CRITICAL)
+
+Suite names MUST be unique and specific to the feature, issue, or user flow:
+- GOOD: `login-valid-credentials`, `issue-1743-auth-redirect`, `checkout-payment-flow`
+- BAD: `all`, `test`, `debug`, `new`, `temp`, `main`, `suite`
+
+If testing a GitHub/GitLab issue, include the issue number: `issue-1743-auth-timeout`, `bug-502-duplicate-submit`
+
+Before creating, always call `e2e_list` to verify the name doesn't already exist.
+
 ## Arguments
 
 The user may provide:

package/opencode.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://opencode.ai/schemas/opencode.json",
+  "mcp": {
+    "e2e-runner": {
+      "type": "local",
+      "command": "node",
+      "args": ["bin/mcp-server.js"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matware/e2e-runner",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "mcpName": "io.github.fastslack/e2e-runner",
   "description": "E2E test runner using Chrome Pool (browserless/chrome) with parallel execution",
   "type": "module",
@@ -20,7 +20,11 @@
     ".mcp.json",
     "skills/",
     "commands/",
-    "agents/"
+    "agents/",
+    ".opencode/",
+    "opencode.json",
+    "OPENCODE.md",
+    "scripts/setup-opencode.sh"
   ],
   "keywords": [
     "e2e",
@@ -31,6 +35,7 @@
     "parallel",
     "mcp",
     "claude-code",
+    "opencode",
     "github-issues",
     "ai-testing"
   ],