@vizzly-testing/cli 0.29.6 → 0.31.0

package/dist/server/routers/events.js

@@ -3,133 +3,213 @@
  * Server-Sent Events endpoint for real-time dashboard updates
  */
 
-import { existsSync, readFileSync, watch } from 'node:fs';
+import { existsSync, readFileSync, statSync, watch } from 'node:fs';
 import { join } from 'node:path';
+let FILE_WATCH_DEBOUNCE_MS = 25;
+let FILE_POLL_INTERVAL_MS = 50;
+let REPORT_READ_RETRY_MS = 25;
+let MAX_REPORT_READ_RETRIES = 3;
+let defaultTimers = {
+  setTimeout,
+  clearTimeout,
+  setInterval,
+  clearInterval
+};
 
 /**
- * Create events router for SSE
- * @param {Object} context - Router context
- * @param {string} context.workingDir - Working directory for report data
- * @returns {Function} Route handler
+ * Read and parse JSON from disk, returning null on missing or invalid files.
  */
-export function createEventsRouter(context) {
-  const {
-    workingDir = process.cwd()
-  } = context || {};
-  const reportDataPath = join(workingDir, '.vizzly', 'report-data.json');
-  const baselineMetadataPath = join(workingDir, '.vizzly', 'baselines', 'metadata.json');
+export function readJsonFile(path) {
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
 
-  /**
-   * Read and parse baseline metadata, returning null on error
-   */
-  const readBaselineMetadata = () => {
-    if (!existsSync(baselineMetadataPath)) {
-      return null;
-    }
-    try {
-      return JSON.parse(readFileSync(baselineMetadataPath, 'utf8'));
-    } catch {
-      return null;
-    }
+/**
+ * Read report data and attach baseline metadata for the stats view.
+ */
+export function readReportDataFile({
+  reportDataPath,
+  baselineMetadataPath
+}) {
+  let data = readJsonFile(reportDataPath);
+  if (!data) {
+    return null;
+  }
+  return {
+    ...data,
+    baseline: readJsonFile(baselineMetadataPath)
   };
+}
 
-  /**
-   * Read and parse report data with baseline metadata included
-   */
-  const readReportData = () => {
-    if (!existsSync(reportDataPath)) {
-      return null;
+/**
+ * Build a lookup map from comparisons array keyed by id
+ */
+function buildComparisonMap(comparisons) {
+  let map = new Map();
+  for (let c of comparisons) {
+    map.set(c.id, c);
+  }
+  return map;
+}
+function comparisonChanged(oldComp, newComp) {
+  return JSON.stringify(oldComp) !== JSON.stringify(newComp);
+}
+
+/**
+ * Extract summary fields (everything except comparisons) for diffing
+ */
+function extractSummary(data) {
+  let {
+    comparisons: _c,
+    ...summary
+  } = data;
+  return summary;
+}
+
+/**
+ * Check if summary-level fields changed between old and new data
+ */
+function summaryChanged(oldData, newData) {
+  let oldSummary = extractSummary(oldData);
+  let newSummary = extractSummary(newData);
+  return JSON.stringify(oldSummary) !== JSON.stringify(newSummary);
+}
+
+/**
+ * Build incremental SSE events by diffing old vs new report data.
+ */
+export function buildReportDataEvents(oldData, newData) {
+  if (!oldData) {
+    return [{
+      type: 'reportData',
+      data: newData
+    }];
+  }
+  let events = [];
+  let oldComparisons = oldData.comparisons || [];
+  let newComparisons = newData.comparisons || [];
+  let oldMap = buildComparisonMap(oldComparisons);
+  let newMap = buildComparisonMap(newComparisons);
+
+  // New or changed comparisons send the full comparison object, not a partial delta.
+  for (let [id, newComp] of newMap) {
+    let oldComp = oldMap.get(id);
+    if (!oldComp || comparisonChanged(oldComp, newComp)) {
+      events.push({
+        type: 'comparisonUpdate',
+        data: newComp
+      });
+    }
+  }
+  for (let [id] of oldMap) {
+    if (!newMap.has(id)) {
+      events.push({
+        type: 'comparisonRemoved',
+        data: {
+          id
+        }
+      });
     }
+  }
+  if (summaryChanged(oldData, newData)) {
+    events.push({
+      type: 'summaryUpdate',
+      data: extractSummary(newData)
+    });
+  }
+  return events;
+}
+
+/**
+ * Watch report-data.json with fs.watch plus a lightweight mtime fallback.
+ */
+export function watchReportDataFile({
+  workingDir,
+  reportDataPath,
+  onReportDataChanged,
+  timers = defaultTimers
+}) {
+  let watcher = null;
+  let filePollInterval = null;
+  let vizzlyDir = join(workingDir, '.vizzly');
+  if (existsSync(vizzlyDir)) {
     try {
-      const data = JSON.parse(readFileSync(reportDataPath, 'utf8'));
-      // Include baseline metadata for stats view
-      data.baseline = readBaselineMetadata();
-      return data;
+      watcher = watch(vizzlyDir, {
+        recursive: false
+      }, (_eventType, filename) => {
+        // Some platforms occasionally omit the filename for directory watch
+        // events. In that case, fall back to re-reading report data.
+        if (!filename || filename === 'report-data.json') {
+          onReportDataChanged();
+        }
+      });
+      watcher.on('error', () => {
+        if (watcher) {
+          watcher.close();
+          watcher = null;
+        }
+      });
     } catch {
-      return null;
+      // File watching not available, mtime polling remains as fallback.
+    }
+  }
+  let lastPolledMtime = existsSync(reportDataPath) ? statSync(reportDataPath).mtimeMs : null;
+  filePollInterval = timers.setInterval(() => {
+    let nextMtime = null;
+    if (existsSync(reportDataPath)) {
+      try {
+        nextMtime = statSync(reportDataPath).mtimeMs;
+      } catch {
+        nextMtime = null;
+      }
+    }
+    if (nextMtime !== lastPolledMtime) {
+      lastPolledMtime = nextMtime;
+      onReportDataChanged();
+    }
+  }, FILE_POLL_INTERVAL_MS);
+  return () => {
+    if (watcher) {
+      watcher.close();
+      watcher = null;
+    }
+    if (filePollInterval) {
+      timers.clearInterval(filePollInterval);
+      filePollInterval = null;
     }
   };
+}
+
+/**
+ * Create events router for SSE
+ * @param {Object} context - Router context
+ * @param {string} context.workingDir - Working directory for report data
+ * @returns {Function} Route handler
+ */
+export function createEventsRouter(context) {
+  let {
+    workingDir = process.cwd(),
+    readReportData = readReportDataFile,
+    watchReportData = watchReportDataFile,
+    timers = defaultTimers
+  } = context || {};
+  let reportDataPath = join(workingDir, '.vizzly', 'report-data.json');
+  let baselineMetadataPath = join(workingDir, '.vizzly', 'baselines', 'metadata.json');
 
   /**
    * Send SSE event to response
    */
-  const sendEvent = (res, eventType, data) => {
+  let sendEvent = (res, eventType, data) => {
     if (res.writableEnded) return;
     res.write(`event: ${eventType}\n`);
     res.write(`data: ${JSON.stringify(data)}\n\n`);
   };
-
-  /**
-   * Build a lookup map from comparisons array keyed by id
-   */
-  const buildComparisonMap = comparisons => {
-    let map = new Map();
-    for (let c of comparisons) {
-      map.set(c.id, c);
-    }
-    return map;
-  };
-  const comparisonChanged = (oldComp, newComp) => {
-    return JSON.stringify(oldComp) !== JSON.stringify(newComp);
-  };
-
-  /**
-   * Extract summary fields (everything except comparisons) for diffing
-   */
-  const extractSummary = data => {
-    let {
-      comparisons: _c,
-      ...summary
-    } = data;
-    return summary;
-  };
-
-  /**
-   * Check if summary-level fields changed between old and new data
-   */
-  const summaryChanged = (oldData, newData) => {
-    let oldSummary = extractSummary(oldData);
-    let newSummary = extractSummary(newData);
-    return JSON.stringify(oldSummary) !== JSON.stringify(newSummary);
-  };
-
-  /**
-   * Send incremental updates by diffing old vs new report data.
-   * Returns true if any events were sent.
-   */
-  const sendIncrementalUpdates = (res, oldData, newData) => {
-    let sent = false;
-    let oldComparisons = oldData.comparisons || [];
-    let newComparisons = newData.comparisons || [];
-    let oldMap = buildComparisonMap(oldComparisons);
-    let newMap = buildComparisonMap(newComparisons);
-
-    // New or changed comparisons — sends the full comparison object, not a partial delta
-    for (let [id, newComp] of newMap) {
-      let oldComp = oldMap.get(id);
-      if (!oldComp || comparisonChanged(oldComp, newComp)) {
-        sendEvent(res, 'comparisonUpdate', newComp);
-        sent = true;
-      }
-    }
-
-    // Removed comparisons
-    for (let [id] of oldMap) {
-      if (!newMap.has(id)) {
-        sendEvent(res, 'comparisonRemoved', {
-          id
-        });
-        sent = true;
-      }
-    }
-
-    // Summary-level changes (total, passed, failed, etc.)
-    if (summaryChanged(oldData, newData)) {
-      sendEvent(res, 'summaryUpdate', extractSummary(newData));
-      sent = true;
-    }
-    return sent;
-  };
   return async function handleEventsRoute(req, res, pathname) {
     if (req.method !== 'GET' || pathname !== '/api/events') {
       return false;
@@ -144,52 +224,51 @@ export function createEventsRouter(context) {
     });
 
     // Send initial full data immediately
-    let lastSentData = readReportData();
+    let lastSentData = readReportData({
+      reportDataPath,
+      baselineMetadataPath
+    });
     if (lastSentData) {
       sendEvent(res, 'reportData', lastSentData);
     }
 
     // Debounce file change events (fs.watch can fire multiple times)
     let debounceTimer = null;
-    let watcher = null;
-    const sendUpdate = () => {
-      const newData = readReportData();
-      if (!newData) return;
-      if (!lastSentData) {
-        // No previous data — send full payload
-        sendEvent(res, 'reportData', newData);
-      } else {
-        // Diff and send incremental updates
-        let sent = sendIncrementalUpdates(res, lastSentData, newData);
-        // If nothing changed, skip (no event needed)
-        if (!sent) return;
+    let scheduleUpdate = () => {
+      if (debounceTimer) {
+        timers.clearTimeout(debounceTimer);
       }
-      lastSentData = newData;
+      debounceTimer = timers.setTimeout(sendUpdate, FILE_WATCH_DEBOUNCE_MS);
     };
-
-    // Watch for file changes
-    const vizzlyDir = join(workingDir, '.vizzly');
-    if (existsSync(vizzlyDir)) {
-      try {
-        watcher = watch(vizzlyDir, {
-          recursive: false
-        }, (_eventType, filename) => {
-          // Only react to report-data.json changes
-          if (filename === 'report-data.json') {
-            // Debounce: wait 100ms after last change before sending
-            if (debounceTimer) {
-              clearTimeout(debounceTimer);
-            }
-            debounceTimer = setTimeout(sendUpdate, 100);
-          }
-        });
-      } catch {
-        // File watching not available, client will fall back to polling
+    let sendUpdate = (retryCount = 0) => {
+      let newData = readReportData({
+        reportDataPath,
+        baselineMetadataPath
+      });
+      if (!newData) {
+        if (existsSync(reportDataPath) && retryCount < MAX_REPORT_READ_RETRIES) {
+          debounceTimer = timers.setTimeout(() => sendUpdate(retryCount + 1), REPORT_READ_RETRY_MS);
+        }
+        return;
       }
-    }
+      let events = buildReportDataEvents(lastSentData, newData);
+      if (events.length === 0) {
+        return;
+      }
+      for (let event of events) {
+        sendEvent(res, event.type, event.data);
+      }
+      lastSentData = newData;
+    };
+    let cleanupReportWatcher = watchReportData({
+      workingDir,
+      reportDataPath,
+      onReportDataChanged: scheduleUpdate,
+      timers
+    });
 
     // Heartbeat to keep connection alive (every 30 seconds)
-    const heartbeatInterval = setInterval(() => {
+    let heartbeatInterval = timers.setInterval(() => {
       if (!res.writableEnded) {
         sendEvent(res, 'heartbeat', {
           timestamp: Date.now()
@@ -198,14 +277,13 @@ export function createEventsRouter(context) {
     }, 30000);
 
     // Cleanup on connection close
-    const cleanup = () => {
+    let cleanup = () => {
       if (debounceTimer) {
-        clearTimeout(debounceTimer);
-      }
-      clearInterval(heartbeatInterval);
-      if (watcher) {
-        watcher.close();
+        timers.clearTimeout(debounceTimer);
+        debounceTimer = null;
       }
+      timers.clearInterval(heartbeatInterval);
+      cleanupReportWatcher();
     };
     req.on('close', cleanup);
     req.on('error', cleanup);

package/dist/server/routers/projects.js

@@ -43,11 +43,15 @@ export function createProjectsRouter({
     const projectBuildsMatch = pathname.match(/^\/api\/projects\/([^/]+)\/([^/]+)\/builds$/);
     if (req.method === 'GET' && projectBuildsMatch) {
       try {
-        const organizationSlug = decodeURIComponent(projectBuildsMatch[1]);
-        const projectSlug = decodeURIComponent(projectBuildsMatch[2]);
-        const limit = parseInt(parsedUrl.searchParams.get('limit') || '20', 10);
-        const branch = parsedUrl.searchParams.get('branch') || undefined;
-        const builds = await projectService.getRecentBuilds(projectSlug, organizationSlug, {
+        let organizationSlug = decodeURIComponent(projectBuildsMatch[1]);
+        let projectSlug = decodeURIComponent(projectBuildsMatch[2]);
+        let limit = parseLimitParam(parsedUrl.searchParams.get('limit'));
+        if (limit === null) {
+          sendError(res, 400, 'limit must be a positive integer');
+          return true;
+        }
+        let branch = parsedUrl.searchParams.get('branch') || undefined;
+        let builds = await projectService.getRecentBuilds(projectSlug, organizationSlug, {
           limit,
           branch
         });
@@ -65,4 +69,9 @@ export function createProjectsRouter({
     }
     return false;
   };
+}
+function parseLimitParam(value) {
+  if (value === null) return 20;
+  if (!/^[1-9]\d*$/.test(value)) return null;
+  return Number(value);
 }

package/dist/server/routers/screenshot.js

@@ -1,6 +1,6 @@
 /**
  * Screenshot Router
- * Handles screenshot uploads and legacy baseline accept
+ * Handles screenshot uploads and flush requests.
  */
 
 import * as output from '../../utils/output.js';
@@ -85,36 +85,6 @@ export function createScreenshotRouter({
         return true;
       }
     }
-
-    // Legacy accept-baseline endpoint
-    if (pathname === '/accept-baseline') {
-      try {
-        const body = await parseJsonBody(req);
-        const {
-          id
-        } = body;
-        if (!id) {
-          sendError(res, 400, 'comparison ID is required');
-          return true;
-        }
-        if (screenshotHandler.acceptBaseline) {
-          const result = await screenshotHandler.acceptBaseline(id);
-          sendJson(res, 200, {
-            success: true,
-            ...result
-          });
-        } else {
-          sendError(res, 501, 'Accept baseline not implemented');
-        }
-        return true;
-      } catch (error) {
-        output.debug('Accept baseline error:', {
-          error: error.message
-        });
-        sendError(res, 500, 'Failed to accept baseline');
-        return true;
-      }
-    }
     return false;
   };
 }

package/dist/services/build-manager.js

@@ -1,120 +1,42 @@
 /**
- * Build Manager - Pure functions for build lifecycle management
+ * Build Manager - local build object creation for the test runner.
  */
 
-import crypto from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 
 /**
- * Generate unique build ID for local build management only.
- * Note: The API generates its own UUIDs for actual builds - this local ID
- * is only used for CLI internal tracking and is not sent to the API.
- * @returns {string} Build ID
- */
-export function generateBuildId() {
-  return `build-${crypto.randomUUID()}`;
-}
-
-/**
- * Create build object
+ * Create a local build object for test-runner orchestration.
+ *
+ * The API creates persisted build IDs. This object is only used inside the
+ * CLI process to give the runner a consistent shape before API creation.
+ *
  * @param {Object} buildOptions - Build configuration
+ * @param {Object} [deps]
+ * @param {Function} [deps.randomId]
+ * @param {Function} [deps.now]
+ * @param {Function} [deps.timestamp]
  * @returns {Object} Build object
  */
-export function createBuildObject(buildOptions) {
-  const {
+export function createBuildObject(buildOptions, deps = {}) {
+  let {
     name,
     branch,
     commit,
     environment = 'test',
     metadata = {}
   } = buildOptions;
+  let randomId = deps.randomId || randomUUID;
+  let now = deps.now || (() => new Date().toISOString());
+  let timestamp = deps.timestamp || Date.now;
   return {
-    id: generateBuildId(),
-    name: name || `build-${Date.now()}`,
+    id: `build-${randomId()}`,
+    name: name || `build-${timestamp()}`,
     branch,
     commit,
     environment,
     metadata,
     status: 'pending',
-    createdAt: new Date().toISOString(),
+    createdAt: now(),
     screenshots: []
   };
-}
-
-/**
- * Update build with new status and data
- * @param {Object} build - Current build
- * @param {string} status - New status
- * @param {Object} updates - Additional updates
- * @returns {Object} Updated build
- */
-export function updateBuild(build, status, updates = {}) {
-  return {
-    ...build,
-    status,
-    updatedAt: new Date().toISOString(),
-    ...updates
-  };
-}
-
-/**
- * Add screenshot to build
- * @param {Object} build - Current build
- * @param {Object} screenshot - Screenshot data
- * @returns {Object} Updated build
- */
-export function addScreenshotToBuild(build, screenshot) {
-  return {
-    ...build,
-    screenshots: [...build.screenshots, {
-      ...screenshot,
-      addedAt: new Date().toISOString()
-    }]
-  };
-}
-
-/**
- * Finalize build with result
- * @param {Object} build - Current build
- * @param {Object} result - Build result
- * @returns {Object} Finalized build
- */
-export function finalizeBuildObject(build, result = {}) {
-  const finalStatus = result.success ? 'completed' : 'failed';
-  return {
-    ...build,
-    status: finalStatus,
-    completedAt: new Date().toISOString(),
-    result
-  };
-}
-
-/**
- * Create queued build item
- * @param {Object} buildOptions - Build options
- * @returns {Object} Queued build item
- */
-export function createQueuedBuild(buildOptions) {
-  return {
-    ...buildOptions,
-    queuedAt: new Date().toISOString()
-  };
-}
-
-/**
- * Validate build options
- * @param {Object} buildOptions - Build options to validate
- * @returns {Object} Validation result
- */
-export function validateBuildOptions(buildOptions) {
-  let errors = [];
-  if (!buildOptions.name && !buildOptions.branch) {
-    errors.push('Either name or branch is required');
-  }
-  if (buildOptions.environment && !['test', 'staging', 'production'].includes(buildOptions.environment)) {
-    errors.push('Environment must be one of: test, staging, production');
-  }
-  return {
-    valid: errors.length === 0,
-    errors
-  };
 }