@vizzly-testing/cli 0.1.0

package/dist/commands/upload.js

@@ -0,0 +1,181 @@
+import { loadConfig } from '../utils/config-loader.js';
+import { ConsoleUI } from '../utils/console-ui.js';
+import { createServiceContainer } from '../container/index.js';
+import { detectBranch, detectCommit, getCommitMessage, generateBuildNameWithGit } from '../utils/git.js';
+import { ApiService } from '../services/api-service.js';
+
+/**
+ * Construct proper build URL with org/project context
+ * @param {string} buildId - Build ID
+ * @param {string} apiUrl - API base URL
+ * @param {string} apiToken - API token
+ * @returns {Promise<string>} Proper build URL
+ */
+async function constructBuildUrl(buildId, apiUrl, apiToken) {
+  try {
+    const apiService = new ApiService({
+      baseUrl: apiUrl,
+      token: apiToken,
+      command: 'upload'
+    });
+    const tokenContext = await apiService.getTokenContext();
+    const baseUrl = apiUrl.replace(/\/api.*$/, '');
+    if (tokenContext.organization?.slug && tokenContext.project?.slug) {
+      return `${baseUrl}/${tokenContext.organization.slug}/${tokenContext.project.slug}/builds/${buildId}`;
+    }
+  } catch (error) {
+    // Fall back to simple URL if context fetch fails
+    console.debug('Failed to fetch token context, using fallback URL:', error.message);
+  }
+
+  // Fallback URL construction
+  const baseUrl = apiUrl.replace(/\/api.*$/, '');
+  return `${baseUrl}/builds/${buildId}`;
+}
+
+/**
+ * Upload command implementation
+ * @param {string} screenshotsPath - Path to screenshots
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function uploadCommand(screenshotsPath, options = {}, globalOptions = {}) {
+  // Create UI handler
+  const ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+
+  // Note: ConsoleUI handles cleanup via global process listeners
+
+  try {
+    ui.info('Starting upload process...');
+
+    // Load configuration with CLI overrides
+    const allOptions = {
+      ...globalOptions,
+      ...options
+    };
+    const config = await loadConfig(globalOptions.config, allOptions);
+
+    // Validate API token
+    if (!config.apiKey) {
+      ui.error('API token required. Use --token or set VIZZLY_TOKEN environment variable');
+      return; // Won't reach here due to process.exit in error()
+    }
+
+    // Collect git metadata if not provided
+    const branch = await detectBranch(options.branch);
+    const commit = await detectCommit(options.commit);
+    const message = options.message || (await getCommitMessage());
+    const buildName = await generateBuildNameWithGit(options.buildName);
+    ui.info(`Uploading screenshots from: ${screenshotsPath}`);
+    if (globalOptions.verbose) {
+      ui.info('Configuration loaded', {
+        branch,
+        commit: commit?.substring(0, 7),
+        environment: config.build.environment,
+        buildName: config.build.name
+      });
+    }
+
+    // Get uploader service
+    ui.startSpinner('Initializing uploader...');
+    const container = await createServiceContainer(config, 'upload');
+    const uploader = await container.get('uploader');
+
+    // Prepare upload options with progress callback
+    const uploadOptions = {
+      screenshotsDir: screenshotsPath,
+      buildName,
+      branch,
+      commit,
+      message,
+      environment: config.build.environment,
+      threshold: config.comparison.threshold,
+      metadata: options.metadata ? JSON.parse(options.metadata) : {},
+      onProgress: progressData => {
+        const {
+          message: progressMessage,
+          current,
+          total,
+          phase
+        } = progressData;
+        ui.progress(progressMessage || `${phase || 'Processing'}: ${current || 0}/${total || 0}`, current, total);
+      }
+    };
+
+    // Start upload
+    ui.progress('Starting upload...');
+    const result = await uploader.upload(uploadOptions);
+    ui.success('Upload completed successfully');
+
+    // Show Vizzly summary
+    if (result.buildId) {
+      ui.info(`🐻 Vizzly: Uploaded ${result.stats.uploaded} of ${result.stats.total} screenshots to build ${result.buildId}`);
+      // Use API-provided URL or construct proper URL with org/project context
+      const buildUrl = result.url || (await constructBuildUrl(result.buildId, config.apiUrl, config.apiKey));
+      ui.info(`🔗 Vizzly: View results at ${buildUrl}`);
+    }
+
+    // Wait for build completion if requested
+    if (options.wait && result.buildId) {
+      ui.info('Waiting for build completion...');
+      ui.startSpinner('Processing comparisons...');
+      const buildResult = await uploader.waitForBuild(result.buildId);
+      ui.success('Build processing completed');
+
+      // Show build processing results
+      if (buildResult.failedComparisons > 0) {
+        ui.warning(`${buildResult.failedComparisons} visual comparisons failed`);
+      } else {
+        ui.success(`All ${buildResult.passedComparisons} visual comparisons passed`);
+      }
+      // Use API-provided URL or construct proper URL with org/project context
+      const buildUrl = buildResult.url || (await constructBuildUrl(result.buildId, config.apiUrl, config.apiKey));
+      ui.info(`🔗 Vizzly: View results at ${buildUrl}`);
+    }
+    ui.cleanup();
+  } catch (error) {
+    ui.error('Upload failed', error);
+  }
+}
+
+/**
+ * Validate upload options
+ * @param {string} screenshotsPath - Path to screenshots
+ * @param {Object} options - Command options
+ */
+export function validateUploadOptions(screenshotsPath, options) {
+  const errors = [];
+  if (!screenshotsPath) {
+    errors.push('Screenshots path is required');
+  }
+  if (options.metadata) {
+    try {
+      JSON.parse(options.metadata);
+    } catch {
+      errors.push('Invalid JSON in --metadata option');
+    }
+  }
+  if (options.threshold !== undefined) {
+    const threshold = parseFloat(options.threshold);
+    if (isNaN(threshold) || threshold < 0 || threshold > 1) {
+      errors.push('Threshold must be a number between 0 and 1');
+    }
+  }
+  if (options.batchSize !== undefined) {
+    const n = parseInt(options.batchSize, 10);
+    if (!Number.isFinite(n) || n <= 0) {
+      errors.push('Batch size must be a positive integer');
+    }
+  }
+  if (options.uploadTimeout !== undefined) {
+    const n = parseInt(options.uploadTimeout, 10);
+    if (!Number.isFinite(n) || n <= 0) {
+      errors.push('Upload timeout must be a positive integer (milliseconds)');
+    }
+  }
+  return errors;
+}

package/dist/container/index.js

@@ -0,0 +1,184 @@
+import { EventEmitter } from 'events';
+import { VizzlyError } from '../errors/vizzly-error.js';
+
+/**
+ * @typedef {Object} ServiceDefinition
+ * @property {Function} factory - Factory function to create service instance
+ * @property {boolean} [singleton=true] - Whether to cache the instance
+ * @property {string[]} [dependencies=[]] - Array of dependency names
+ */
+
+/**
+ * Service container for dependency injection and lifecycle management
+ */
+export class ServiceContainer extends EventEmitter {
+  constructor() {
+    super();
+    this.services = new Map();
+    this.instances = new Map();
+    this.starting = new Map();
+  }
+
+  /**
+   * Register a service
+   * @param {string} name - Service name
+   * @param {Function|ServiceDefinition} factoryOrDefinition - Factory function or service definition
+   */
+  register(name, factoryOrDefinition) {
+    const definition = typeof factoryOrDefinition === 'function' ? {
+      factory: factoryOrDefinition,
+      singleton: true,
+      dependencies: []
+    } : factoryOrDefinition;
+    this.services.set(name, definition);
+    this.emit('service:registered', {
+      name,
+      definition
+    });
+  }
+
+  /**
+   * Get a service instance
+   * @param {string} name - Service name
+   * @returns {Promise<any>} Service instance
+   */
+  async get(name) {
+    if (!this.services.has(name)) {
+      throw new VizzlyError(`Service '${name}' not registered`, 'SERVICE_NOT_FOUND', {
+        name
+      });
+    }
+    const definition = this.services.get(name);
+
+    // Return cached instance for singletons
+    if (definition.singleton && this.instances.has(name)) {
+      return this.instances.get(name);
+    }
+
+    // Prevent circular dependencies during startup
+    if (this.starting.has(name)) {
+      throw new VizzlyError(`Circular dependency detected for service '${name}'`, 'CIRCULAR_DEPENDENCY', {
+        name
+      });
+    }
+    try {
+      this.starting.set(name, true);
+
+      // Resolve dependencies
+      const deps = await Promise.all((definition.dependencies || []).map(dep => this.get(dep)));
+
+      // Create instance
+      const instance = await definition.factory(...deps);
+
+      // Cache singleton instances
+      if (definition.singleton) {
+        this.instances.set(name, instance);
+      }
+      this.emit('service:created', {
+        name,
+        instance
+      });
+      return instance;
+    } finally {
+      this.starting.delete(name);
+    }
+  }
+
+  /**
+   * Start all registered services
+   */
+  async startAll() {
+    const services = Array.from(this.services.keys());
+    for (const name of services) {
+      const instance = await this.get(name);
+      if (instance && typeof instance.start === 'function') {
+        await instance.start();
+        this.emit('service:started', {
+          name,
+          instance
+        });
+      }
+    }
+  }
+
+  /**
+   * Stop all services in reverse order
+   */
+  async stopAll() {
+    const instances = Array.from(this.instances.entries()).reverse();
+    for (const [name, instance] of instances) {
+      if (instance && typeof instance.stop === 'function') {
+        await instance.stop();
+        this.emit('service:stopped', {
+          name,
+          instance
+        });
+      }
+    }
+  }
+
+  /**
+   * Clear all services and instances
+   */
+  clear() {
+    this.services.clear();
+    this.instances.clear();
+    this.starting.clear();
+  }
+}
+
+// Export singleton instance
+export const container = new ServiceContainer();
+/**
+ * Create a configured service container
+ * @param {Object} config - Configuration object
+ * @returns {ServiceContainer}
+ */
+export async function createServiceContainer(config, command = 'run') {
+  const container = new ServiceContainer();
+
+  // Dynamic ESM imports to avoid circular deps
+  const [{
+    createComponentLogger
+  }, {
+    ApiService
+  }, {
+    createUploader
+  }, {
+    createTDDService
+  }, {
+    TestRunner
+  }, {
+    BuildManager
+  }, {
+    ServerManager
+  }] = await Promise.all([import('../utils/logger-factory.js'), import('../services/api-service.js'), import('../services/uploader.js'), import('../services/tdd-service.js'), import('../services/test-runner.js'), import('../services/build-manager.js'), import('../services/server-manager.js')]);
+
+  // Create logger instance once
+  const logger = createComponentLogger('CONTAINER', {
+    level: config.logLevel || (config.verbose ? 'debug' : 'warn'),
+    verbose: config.verbose || false
+  });
+
+  // Register services without circular dependencies
+  container.register('logger', () => logger);
+  container.register('apiService', () => new ApiService(config, {
+    logger
+  }));
+  container.register('uploader', () => createUploader({
+    ...config,
+    command
+  }, {
+    logger
+  }));
+  container.register('buildManager', () => new BuildManager(config, logger));
+  container.register('serverManager', () => new ServerManager(config, logger));
+  container.register('tddService', () => createTDDService(config, {
+    logger
+  }));
+  container.register('testRunner', {
+    factory: async (buildManager, serverManager, tddService) => new TestRunner(config, logger, buildManager, serverManager, tddService),
+    dependencies: ['buildManager', 'serverManager', 'tddService']
+  });
+  return container;
+}

package/dist/errors/vizzly-error.js

@@ -0,0 +1,149 @@
+/**
+ * Base error class for all Vizzly errors
+ * Provides consistent error structure and helpful debugging information
+ */
+export class VizzlyError extends Error {
+  constructor(message, code = 'VIZZLY_ERROR', context = {}) {
+    super(message);
+    this.name = 'VizzlyError';
+    this.code = code;
+    this.context = context;
+    this.timestamp = new Date().toISOString();
+  }
+
+  /**
+   * Get a user-friendly error message
+   */
+  getUserMessage() {
+    return this.message;
+  }
+
+  /**
+   * Get error details for logging
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      context: this.context,
+      timestamp: this.timestamp,
+      stack: this.stack
+    };
+  }
+}
+
+/**
+ * Configuration-related errors
+ */
+export class ConfigError extends VizzlyError {
+  constructor(message, context = {}) {
+    super(message, 'CONFIG_ERROR', context);
+    this.name = 'ConfigError';
+  }
+  getUserMessage() {
+    return `Configuration error: ${this.message}. Please check your vizzly.config.js file.`;
+  }
+}
+
+/**
+ * Authentication/authorization errors
+ */
+export class AuthError extends VizzlyError {
+  constructor(message, context = {}) {
+    super(message, 'AUTH_ERROR', context);
+    this.name = 'AuthError';
+  }
+  getUserMessage() {
+    return `Authentication error: ${this.message}. Please check your VIZZLY_TOKEN.`;
+  }
+}
+
+/**
+ * Network/connection errors
+ */
+export class NetworkError extends VizzlyError {
+  constructor(message, context = {}) {
+    super(message, 'NETWORK_ERROR', context);
+    this.name = 'NetworkError';
+  }
+  getUserMessage() {
+    return `Network error: ${this.message}. Please check your connection.`;
+  }
+}
+
+/**
+ * Upload-related errors
+ */
+export class UploadError extends VizzlyError {
+  constructor(message, context = {}) {
+    super(message, 'UPLOAD_ERROR', context);
+    this.name = 'UploadError';
+  }
+  getUserMessage() {
+    return `Upload failed: ${this.message}`;
+  }
+}
+
+/**
+ * Screenshot-related errors
+ */
+export class ScreenshotError extends VizzlyError {
+  constructor(message, context = {}) {
+    super(message, 'SCREENSHOT_ERROR', context);
+    this.name = 'ScreenshotError';
+  }
+  getUserMessage() {
+    return `Screenshot error: ${this.message}`;
+  }
+}
+
+/**
+ * Build-related errors
+ */
+export class BuildError extends VizzlyError {
+  constructor(message, context = {}) {
+    super(message, 'BUILD_ERROR', context);
+    this.name = 'BuildError';
+  }
+  getUserMessage() {
+    return `Build error: ${this.message}`;
+  }
+}
+
+/**
+ * Timeout errors
+ */
+export class TimeoutError extends VizzlyError {
+  constructor(message, duration, context = {}) {
+    super(message, 'TIMEOUT_ERROR', {
+      duration,
+      ...context
+    });
+    this.name = 'TimeoutError';
+    this.duration = duration;
+  }
+  getUserMessage() {
+    return `Operation timed out after ${this.duration}ms: ${this.message}`;
+  }
+}
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends VizzlyError {
+  constructor(message, errors = [], context = {}) {
+    super(message, 'VALIDATION_ERROR', {
+      errors,
+      ...context
+    });
+    this.name = 'ValidationError';
+    this.errors = errors;
+  }
+  getUserMessage() {
+    if (this.errors.length > 0) {
+      return `${this.message}: ${this.errors.join(', ')}`;
+    }
+    return this.message;
+  }
+}

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * Vizzly CLI & SDK - Main exports
+ *
+ * This is the main entry point. For specific use cases:
+ * - Test runners: import from '@vizzly-testing/cli/client'
+ * - Custom integrations: import from '@vizzly-testing/cli/sdk'
+ */
+
+// Primary SDK export
+export { createVizzly } from './sdk/index.js';
+
+// Client exports for convenience
+export { vizzlyScreenshot, configure, setEnabled } from './client/index.js';
+
+// Core services (for advanced usage)
+export { createUploader } from './services/uploader.js';
+export { createTDDService } from './services/tdd-service.js';
+
+// Service container
+export { ServiceContainer, container } from './container/index.js';
+export { BaseService } from './services/base-service.js';
+
+// Utilities
+export { loadConfig } from './utils/config-loader.js';
+export { createLogger } from './utils/logger.js';
+
+// Configuration helper
+export { defineConfig } from './utils/config-helpers.js';
+
+// Errors
+export { UploadError } from './errors/vizzly-error.js';

package/dist/screenshot-wrapper.js

@@ -0,0 +1,68 @@
+/**
+ * Simple factory for creating Vizzly instances with shared configuration
+ * Users handle their own screenshots, just pass the buffer to Vizzly
+ */
+
+import { createVizzly as createVizzlySDK } from './vizzly.js';
+
+/**
+ * Create a factory that pre-configures Vizzly instances
+ *
+ * @param {Object} config - Shared configuration
+ * @param {Object} [config.defaultProperties] - Default metadata for all screenshots
+ * @param {number} [config.defaultThreshold] - Default comparison threshold
+ *
+ * @example
+ * // test-setup.js - Configure once
+ * export const createVizzly = vizzlyFactory({
+ *   defaultProperties: {
+ *     framework: 'playwright',
+ *     project: 'web-app'
+ *   }
+ * });
+ *
+ * // my-test.spec.js - Use everywhere
+ * const vizzly = createVizzly();
+ *
+ * const screenshot = await page.screenshot({ fullPage: true }); // Your method
+ * await vizzly.screenshot({
+ *   name: 'homepage',
+ *   image: screenshot, // Your buffer
+ *   properties: { browser: 'chrome' } // Merges with defaults
+ * });
+ */
+export function vizzlyFactory(globalConfig) {
+  const {
+    defaultProperties = {},
+    defaultThreshold,
+    ...vizzlyConfig
+  } = globalConfig;
+  return function createVizzly(overrideConfig = {}) {
+    const vizzly = createVizzlySDK({
+      ...vizzlyConfig,
+      ...overrideConfig
+    });
+    return {
+      ...vizzly,
+      /**
+       * Take a screenshot with default properties merged in
+       *
+       * @param {Object} screenshot - Screenshot object
+       * @param {string} screenshot.name - Screenshot name
+       * @param {Buffer} screenshot.image - Image buffer from YOUR screenshot method
+       * @param {Object} [screenshot.properties] - Additional metadata (merged with defaults)
+       * @param {number} [screenshot.threshold] - Comparison threshold (defaults to global)
+       */
+      async screenshot(screenshot) {
+        return await vizzly.screenshot({
+          ...screenshot,
+          properties: {
+            ...defaultProperties,
+            ...screenshot.properties
+          },
+          threshold: screenshot.threshold || defaultThreshold
+        });
+      }
+    };
+  };
+}