@vizzly-testing/cli 0.19.2 → 0.20.1-beta.0

package/dist/screenshot-server/core.js

@@ -0,0 +1,157 @@
+/**
+ * Screenshot Server Core - Pure functions for screenshot server logic
+ *
+ * No I/O, no side effects - just data transformations.
+ */
+
+// ============================================================================
+// Request Validation
+// ============================================================================
+
+/**
+ * Validate screenshot request body
+ * @param {Object} body - Request body
+ * @returns {{ valid: boolean, error: string|null }}
+ */
+export function validateScreenshotRequest(body) {
+  if (!body?.name || !body?.image) {
+    return {
+      valid: false,
+      error: 'name and image are required'
+    };
+  }
+  return {
+    valid: true,
+    error: null
+  };
+}
+
+/**
+ * Check if request is for the screenshot endpoint
+ * @param {string} method - HTTP method
+ * @param {string} url - Request URL
+ * @returns {boolean}
+ */
+export function isScreenshotEndpoint(method, url) {
+  return method === 'POST' && url === '/screenshot';
+}
+
+// ============================================================================
+// Build ID Handling
+// ============================================================================
+
+/**
+ * Get effective build ID (falls back to 'default')
+ * @param {string|null|undefined} buildId - Build ID from request
+ * @returns {string}
+ */
+export function getEffectiveBuildId(buildId) {
+  return buildId || 'default';
+}
+
+// ============================================================================
+// Response Building
+// ============================================================================
+
+/**
+ * Build success response object
+ * @returns {{ status: number, body: Object }}
+ */
+export function buildSuccessResponse() {
+  return {
+    status: 200,
+    body: {
+      success: true
+    }
+  };
+}
+
+/**
+ * Build error response object
+ * @param {number} status - HTTP status code
+ * @param {string} message - Error message
+ * @returns {{ status: number, body: Object }}
+ */
+export function buildErrorResponse(status, message) {
+  return {
+    status,
+    body: {
+      error: message
+    }
+  };
+}
+
+/**
+ * Build not found response
+ * @returns {{ status: number, body: Object }}
+ */
+export function buildNotFoundResponse() {
+  return buildErrorResponse(404, 'Not found');
+}
+
+/**
+ * Build bad request response
+ * @param {string} message - Error message
+ * @returns {{ status: number, body: Object }}
+ */
+export function buildBadRequestResponse(message) {
+  return buildErrorResponse(400, message);
+}
+
+/**
+ * Build internal error response
+ * @returns {{ status: number, body: Object }}
+ */
+export function buildInternalErrorResponse() {
+  return buildErrorResponse(500, 'Internal server error');
+}
+
+// ============================================================================
+// Server Configuration
+// ============================================================================
+
+/**
+ * Build server listen options
+ * @param {Object} config - Server configuration
+ * @returns {{ port: number, host: string }}
+ */
+export function buildServerListenOptions(config) {
+  return {
+    port: config?.server?.port || 3000,
+    host: '127.0.0.1'
+  };
+}
+
+/**
+ * Build server started message
+ * @param {number} port - Server port
+ * @returns {string}
+ */
+export function buildServerStartedMessage(port) {
+  return `Screenshot server listening on http://127.0.0.1:${port}`;
+}
+
+/**
+ * Build server stopped message
+ * @returns {string}
+ */
+export function buildServerStoppedMessage() {
+  return 'Screenshot server stopped';
+}
+
+// ============================================================================
+// Screenshot Data Extraction
+// ============================================================================
+
+/**
+ * Extract screenshot data from request body
+ * @param {Object} body - Request body
+ * @returns {{ name: string, image: string, properties?: Object }}
+ */
+export function extractScreenshotData(body) {
+  return {
+    name: body.name,
+    image: body.image,
+    properties: body.properties
+  };
+}

package/dist/screenshot-server/index.js

@@ -0,0 +1,11 @@
+/**
+ * Screenshot Server Module
+ *
+ * Exports pure functions (core) and I/O operations for screenshot server functionality.
+ */
+
+// Core - pure functions
+export { buildBadRequestResponse, buildErrorResponse, buildInternalErrorResponse, buildNotFoundResponse, buildServerListenOptions, buildServerStartedMessage, buildServerStoppedMessage, buildSuccessResponse, extractScreenshotData, getEffectiveBuildId, isScreenshotEndpoint, validateScreenshotRequest } from './core.js';
+
+// Operations - I/O with dependency injection
+export { handleRequest, parseRequestBody, startServer, stopServer } from './operations.js';

package/dist/screenshot-server/operations.js

@@ -0,0 +1,183 @@
+/**
+ * Screenshot Server Operations - I/O operations with dependency injection
+ *
+ * Each operation takes its dependencies as parameters for testability.
+ */
+
+import { buildBadRequestResponse, buildInternalErrorResponse, buildNotFoundResponse, buildServerListenOptions, buildServerStartedMessage, buildServerStoppedMessage, buildSuccessResponse, extractScreenshotData, getEffectiveBuildId, isScreenshotEndpoint, validateScreenshotRequest } from './core.js';
+
+// ============================================================================
+// Request Body Parsing
+// ============================================================================
+
+/**
+ * Parse request body as JSON
+ * @param {Object} options - Options
+ * @param {Object} options.req - HTTP request
+ * @param {Object} options.deps - Dependencies
+ * @param {Function} options.deps.createError - Error factory
+ * @returns {Promise<Object>} Parsed body
+ */
+export function parseRequestBody({
+  req,
+  deps
+}) {
+  let {
+    createError
+  } = deps;
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', chunk => {
+      body += chunk.toString();
+    });
+    req.on('end', () => {
+      try {
+        resolve(JSON.parse(body));
+      } catch {
+        reject(createError('Invalid JSON in request body', 'INVALID_JSON'));
+      }
+    });
+    req.on('error', error => {
+      reject(createError(`Request error: ${error.message}`, 'REQUEST_ERROR'));
+    });
+  });
+}
+
+// ============================================================================
+// Request Handling
+// ============================================================================
+
+/**
+ * Handle incoming HTTP request
+ * @param {Object} options - Options
+ * @param {Object} options.req - HTTP request
+ * @param {Object} options.res - HTTP response
+ * @param {Object} options.deps - Dependencies
+ * @param {Object} options.deps.buildManager - Build manager for screenshot storage
+ * @param {Function} options.deps.createError - Error factory
+ * @param {Object} options.deps.output - Output utilities
+ */
+export async function handleRequest({
+  req,
+  res,
+  deps
+}) {
+  let {
+    buildManager,
+    createError,
+    output
+  } = deps;
+
+  // Check if this is a screenshot endpoint
+  if (!isScreenshotEndpoint(req.method, req.url)) {
+    let response = buildNotFoundResponse();
+    sendResponse(res, response);
+    return;
+  }
+  try {
+    // Parse request body
+    let body = await parseRequestBody({
+      req,
+      deps: {
+        createError
+      }
+    });
+
+    // Validate required fields
+    let validation = validateScreenshotRequest(body);
+    if (!validation.valid) {
+      let response = buildBadRequestResponse(validation.error);
+      sendResponse(res, response);
+      return;
+    }
+
+    // Process screenshot
+    let effectiveBuildId = getEffectiveBuildId(body.buildId);
+    let screenshotData = extractScreenshotData(body);
+    await buildManager.addScreenshot(effectiveBuildId, screenshotData);
+    let response = buildSuccessResponse();
+    sendResponse(res, response);
+  } catch (error) {
+    output.error('Failed to process screenshot:', error);
+    let response = buildInternalErrorResponse();
+    sendResponse(res, response);
+  }
+}
+
+/**
+ * Send response to client
+ * @param {Object} res - HTTP response
+ * @param {{ status: number, body: Object }} response - Response data
+ */
+function sendResponse(res, response) {
+  res.statusCode = response.status;
+  res.end(JSON.stringify(response.body));
+}
+
+// ============================================================================
+// Server Lifecycle
+// ============================================================================
+
+/**
+ * Start the HTTP server
+ * @param {Object} options - Options
+ * @param {Object} options.config - Server configuration
+ * @param {Function} options.requestHandler - Request handler function
+ * @param {Object} options.deps - Dependencies
+ * @param {Function} options.deps.createHttpServer - HTTP server factory (http.createServer)
+ * @param {Function} options.deps.createError - Error factory
+ * @param {Object} options.deps.output - Output utilities
+ * @returns {Promise<Object>} HTTP server instance
+ */
+export function startServer({
+  config,
+  requestHandler,
+  deps
+}) {
+  let {
+    createHttpServer,
+    createError,
+    output
+  } = deps;
+  return new Promise((resolve, reject) => {
+    let server = createHttpServer(requestHandler);
+    let {
+      port,
+      host
+    } = buildServerListenOptions(config);
+    server.listen(port, host, error => {
+      if (error) {
+        reject(createError(`Failed to start screenshot server: ${error.message}`, 'SERVER_ERROR'));
+      } else {
+        output.info(buildServerStartedMessage(port));
+        resolve(server);
+      }
+    });
+  });
+}
+
+/**
+ * Stop the HTTP server
+ * @param {Object} options - Options
+ * @param {Object|null} options.server - HTTP server instance
+ * @param {Object} options.deps - Dependencies
+ * @param {Object} options.deps.output - Output utilities
+ * @returns {Promise<void>}
+ */
+export function stopServer({
+  server,
+  deps
+}) {
+  let {
+    output
+  } = deps;
+  if (!server) {
+    return Promise.resolve();
+  }
+  return new Promise(resolve => {
+    server.close(() => {
+      output.info(buildServerStoppedMessage());
+      resolve();
+    });
+  });
+}

package/dist/sdk/index.js

@@ -13,8 +13,8 @@
 import { EventEmitter } from 'node:events';
 import { VizzlyError } from '../errors/vizzly-error.js';
 import { ScreenshotServer } from '../services/screenshot-server.js';
-import { createTDDService } from '../services/tdd-service.js';
 import { createUploader } from '../services/uploader.js';
+import { createTDDService } from '../tdd/tdd-service.js';
 import { loadConfig } from '../utils/config-loader.js';
 import { resolveImageBuffer } from '../utils/file-helpers.js';
 import * as output from '../utils/output.js';
@@ -357,9 +357,10 @@ export class VizzlySDK extends EventEmitter {
     }
   }
 }
-export { createTDDService } from '../services/tdd-service.js';
+
 // Export service creators for advanced usage
 export { createUploader } from '../services/uploader.js';
+export { createTDDService } from '../tdd/tdd-service.js';
 // Re-export key utilities and errors
 export { loadConfig } from '../utils/config-loader.js';
 export * as output from '../utils/output.js';

package/dist/server/handlers/api-handler.js

@@ -1,6 +1,7 @@
 import { Buffer } from 'node:buffer';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { uploadScreenshot as defaultUploadScreenshot } from '../../api/index.js';
 import { detectImageInputType } from '../../utils/image-input-detector.js';
 import * as output from '../../utils/output.js';
 
@@ -34,7 +35,15 @@ import * as output from '../../utils/output.js';
  * └─────────────────────────────────────────────────────────────┘
  */
 
-export const createApiHandler = apiService => {
+/**
+ * Create an API handler for screenshot uploads.
+ * @param {Object} client - API client with request method
+ * @param {Object} options - Optional dependencies for testing
+ * @param {Function} options.uploadScreenshot - Upload function (defaults to API uploadScreenshot)
+ */
+export const createApiHandler = (client, {
+  uploadScreenshot = defaultUploadScreenshot
+} = {}) => {
   let vizzlyDisabled = false;
   let screenshotCount = 0;
   let uploadPromises = [];
@@ -52,13 +61,13 @@ export const createApiHandler = apiService => {
       };
     }
 
-    // buildId is optional - API service will handle it appropriately
+    // buildId is optional - API will handle it appropriately
 
-    if (!apiService) {
+    if (!client) {
       return {
         statusCode: 500,
         body: {
-          error: 'API service not available'
+          error: 'API client not available'
         }
       };
     }
@@ -114,7 +123,7 @@ export const createApiHandler = apiService => {
     screenshotCount++;
 
     // Fire upload in background - DON'T AWAIT!
-    const uploadPromise = apiService.uploadScreenshot(buildId, name, imageBuffer, properties ?? {}).then(result => {
+    let uploadPromise = uploadScreenshot(client, buildId, name, imageBuffer, properties ?? {}).then(result => {
       if (!result.skipped) {
         output.debug('upload', name);
       }

package/dist/server/handlers/tdd-handler.js

@@ -1,17 +1,66 @@
-import { Buffer } from 'node:buffer';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { getDimensionsSync } from '@vizzly-testing/honeydiff';
-import { TddService } from '../../services/tdd-service.js';
-import { detectImageInputType } from '../../utils/image-input-detector.js';
-import * as output from '../../utils/output.js';
-import { sanitizeScreenshotName, validateScreenshotProperties } from '../../utils/security.js';
+import { Buffer as defaultBuffer } from 'node:buffer';
+import { existsSync as defaultExistsSync, readFileSync as defaultReadFileSync, writeFileSync as defaultWriteFileSync } from 'node:fs';
+import { join as defaultJoin, resolve as defaultResolve } from 'node:path';
+import { getDimensionsSync as defaultGetDimensionsSync } from '@vizzly-testing/honeydiff';
+import { TddService as DefaultTddService } from '../../tdd/tdd-service.js';
+import { detectImageInputType as defaultDetectImageInputType } from '../../utils/image-input-detector.js';
+import * as defaultOutput from '../../utils/output.js';
+import { sanitizeScreenshotName as defaultSanitizeScreenshotName, validateScreenshotProperties as defaultValidateScreenshotProperties } from '../../utils/security.js';
+
+/**
+ * Unwrap double-nested properties if needed
+ * Client SDK wraps options in properties field, so we may get { properties: { properties: {...} } }
+ */
+export const unwrapProperties = properties => {
+  if (!properties) return {};
+  if (properties.properties && typeof properties.properties === 'object') {
+    // Merge top-level properties with nested properties
+    let unwrapped = {
+      ...properties,
+      ...properties.properties
+    };
+    // Remove the nested properties field to avoid confusion
+    delete unwrapped.properties;
+    return unwrapped;
+  }
+  return properties;
+};
+
+/**
+ * Extract properties to top-level format matching cloud API
+ * Normalizes viewport to viewport_width/height, ensures browser is set
+ */
+export const extractProperties = validatedProperties => {
+  if (!validatedProperties) return {};
+  return {
+    ...validatedProperties,
+    // Normalize viewport to top-level viewport_width/height (cloud format)
+    viewport_width: validatedProperties.viewport?.width ?? validatedProperties.viewport_width ?? null,
+    viewport_height: validatedProperties.viewport?.height ?? validatedProperties.viewport_height ?? null,
+    browser: validatedProperties.browser ?? null,
+    // Preserve nested structure in metadata for backward compatibility
+    metadata: validatedProperties
+  };
+};
+
+/**
+ * Convert absolute file paths to web-accessible URLs
+ */
+export const convertPathToUrl = (filePath, vizzlyDir) => {
+  if (!filePath) return null;
+  // Convert absolute path to relative path from .vizzly directory
+  if (filePath.startsWith(vizzlyDir)) {
+    let relativePath = filePath.substring(vizzlyDir.length + 1);
+    return `/images/${relativePath}`;
+  }
+  return filePath;
+};
 
 /**
  * Group comparisons by screenshot name with variant structure
  * Matches cloud product's grouping logic from comparison.js
  */
-const groupComparisons = comparisons => {
+export const groupComparisons = comparisons => {
   const groups = new Map();
 
   // Group by screenshot name
@@ -87,7 +136,22 @@ const groupComparisons = comparisons => {
     return a.name.localeCompare(b.name);
   });
 };
-export const createTddHandler = (config, workingDir, baselineBuild, baselineComparison, setBaseline = false) => {
+export const createTddHandler = (config, workingDir, baselineBuild, baselineComparison, setBaseline = false, deps = {}) => {
+  // Inject dependencies with defaults
+  let {
+    TddService = DefaultTddService,
+    existsSync = defaultExistsSync,
+    readFileSync = defaultReadFileSync,
+    writeFileSync = defaultWriteFileSync,
+    join = defaultJoin,
+    resolve = defaultResolve,
+    Buffer = defaultBuffer,
+    getDimensionsSync = defaultGetDimensionsSync,
+    detectImageInputType = defaultDetectImageInputType,
+    sanitizeScreenshotName = defaultSanitizeScreenshotName,
+    validateScreenshotProperties = defaultValidateScreenshotProperties,
+    output = defaultOutput
+  } = deps;
   const tddService = new TddService(config, workingDir, setBaseline);
   const reportPath = join(workingDir, '.vizzly', 'report-data.json');
   const readReportData = () => {
@@ -217,18 +281,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
     }
 
     // Unwrap double-nested properties if needed (client SDK wraps options in properties field)
-    // This happens when test helper passes { properties: {...}, threshold: 2.0 }
-    // and client SDK wraps it as { properties: options }
-    let unwrappedProperties = properties;
-    if (properties.properties && typeof properties.properties === 'object') {
-      // Merge top-level properties with nested properties
-      unwrappedProperties = {
-        ...properties,
-        ...properties.properties
-      };
-      // Remove the nested properties field to avoid confusion
-      delete unwrappedProperties.properties;
-    }
+    let unwrappedProperties = unwrapProperties(properties);
 
     // Validate and sanitize properties
     let validatedProperties;
@@ -246,19 +299,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
     }
 
     // Extract ALL properties to top-level (matching cloud API behavior)
-    // This ensures signature generation works correctly for custom properties like theme, device, etc.
-    // Spread all validated properties first, then normalize viewport/browser for cloud format
-    const extractedProperties = {
-      ...validatedProperties,
-      // Normalize viewport to top-level viewport_width/height (cloud format)
-      // Use nullish coalescing to preserve any existing top-level values
-      viewport_width: validatedProperties.viewport?.width ?? validatedProperties.viewport_width ?? null,
-      viewport_height: validatedProperties.viewport?.height ?? validatedProperties.viewport_height ?? null,
-      browser: validatedProperties.browser ?? null,
-      // Preserve nested structure in metadata for backward compatibility
-      // Signature generation checks multiple locations: top-level, metadata.*, metadata.properties.*
-      metadata: validatedProperties
-    };
+    const extractedProperties = extractProperties(validatedProperties);
 
     // Support both base64 encoded images and file paths
     // Vitest browser mode returns file paths, so we need to handle both
@@ -336,16 +377,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
     // Comparison tracked by tdd.js event handler
 
     // Convert absolute file paths to web-accessible URLs
-    const convertPathToUrl = filePath => {
-      if (!filePath) return null;
-      // Convert absolute path to relative path from .vizzly directory
-      const vizzlyDir = join(workingDir, '.vizzly');
-      if (filePath.startsWith(vizzlyDir)) {
-        const relativePath = filePath.substring(vizzlyDir.length + 1);
-        return `/images/${relativePath}`;
-      }
-      return filePath;
-    };
+    const vizzlyDir = join(workingDir, '.vizzly');
 
     // Record the comparison for the dashboard
     const newComparison = {
@@ -354,9 +386,9 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       name: comparison.name,
       originalName: name,
       status: comparison.status,
-      baseline: convertPathToUrl(comparison.baseline),
-      current: convertPathToUrl(comparison.current),
-      diff: convertPathToUrl(comparison.diff),
+      baseline: convertPathToUrl(comparison.baseline, vizzlyDir),
+      current: convertPathToUrl(comparison.current, vizzlyDir),
+      diff: convertPathToUrl(comparison.diff, vizzlyDir),
       diffPercentage: comparison.diffPercentage,
       threshold: comparison.threshold,
       properties: extractedProperties,