@vizzly-testing/cli 0.1.0

package/dist/types/commands/init.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+export function createInitCommand(options: any): () => Promise<void>;
+export function init(options?: {}): Promise<void>;
+/**
+ * Simple configuration setup for Vizzly CLI
+ */
+export class InitCommand {
+    constructor(logger: any);
+    logger: any;
+    run(options?: {}): Promise<void>;
+    generateConfigFile(configPath: any): Promise<void>;
+    showNextSteps(): void;
+    fileExists(filePath: any): Promise<boolean>;
+}

package/dist/types/commands/run.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Run command implementation
+ * @param {string} testCommand - Test command to execute
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export function runCommand(testCommand: string, options?: any, globalOptions?: any): Promise<void>;
+/**
+ * Validate run options
+ * @param {string} testCommand - Test command to execute
+ * @param {Object} options - Command options
+ */
+export function validateRunOptions(testCommand: string, options: any): string[];

package/dist/types/commands/status.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Status command implementation
+ * @param {string} buildId - Build ID to check status for
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export function statusCommand(buildId: string, options?: any, globalOptions?: any): Promise<void>;
+/**
+ * Validate status options
+ * @param {string} buildId - Build ID to check
+ * @param {Object} options - Command options
+ */
+export function validateStatusOptions(buildId: string): string[];

package/dist/types/commands/tdd.d.ts

@@ -0,0 +1,13 @@
+/**
+ * TDD command implementation
+ * @param {string} testCommand - Test command to execute
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export function tddCommand(testCommand: string, options?: any, globalOptions?: any): Promise<void>;
+/**
+ * Validate TDD options
+ * @param {string} testCommand - Test command to execute
+ * @param {Object} options - Command options
+ */
+export function validateTddOptions(testCommand: string, options: any): string[];

package/dist/types/commands/upload.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Upload command implementation
+ * @param {string} screenshotsPath - Path to screenshots
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export function uploadCommand(screenshotsPath: string, options?: any, globalOptions?: any): Promise<void>;
+/**
+ * Validate upload options
+ * @param {string} screenshotsPath - Path to screenshots
+ * @param {Object} options - Command options
+ */
+export function validateUploadOptions(screenshotsPath: string, options: any): string[];

package/dist/types/container/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Create a configured service container
+ * @param {Object} config - Configuration object
+ * @returns {ServiceContainer}
+ */
+export function createServiceContainer(config: any, command?: string): ServiceContainer;
+/**
+ * @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<[never]> {
+    constructor();
+    services: Map<any, any>;
+    instances: Map<any, any>;
+    starting: Map<any, any>;
+    /**
+     * Register a service
+     * @param {string} name - Service name
+     * @param {Function|ServiceDefinition} factoryOrDefinition - Factory function or service definition
+     */
+    register(name: string, factoryOrDefinition: Function | ServiceDefinition): void;
+    /**
+     * Get a service instance
+     * @param {string} name - Service name
+     * @returns {Promise<any>} Service instance
+     */
+    get(name: string): Promise<any>;
+    /**
+     * Start all registered services
+     */
+    startAll(): Promise<void>;
+    /**
+     * Stop all services in reverse order
+     */
+    stopAll(): Promise<void>;
+    /**
+     * Clear all services and instances
+     */
+    clear(): void;
+}
+export const container: ServiceContainer;
+export type ServiceDefinition = {
+    /**
+     * - Factory function to create service instance
+     */
+    factory: Function;
+    /**
+     * - Whether to cache the instance
+     */
+    singleton?: boolean;
+    /**
+     * - Array of dependency names
+     */
+    dependencies?: string[];
+};
+import { EventEmitter } from 'events';

package/dist/types/errors/vizzly-error.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Base error class for all Vizzly errors
+ * Provides consistent error structure and helpful debugging information
+ */
+export class VizzlyError extends Error {
+    constructor(message: any, code?: string, context?: {});
+    code: string;
+    context: {};
+    timestamp: string;
+    /**
+     * Get a user-friendly error message
+     */
+    getUserMessage(): string;
+    /**
+     * Get error details for logging
+     */
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        context: {};
+        timestamp: string;
+        stack: string;
+    };
+}
+/**
+ * Configuration-related errors
+ */
+export class ConfigError extends VizzlyError {
+    constructor(message: any, context?: {});
+}
+/**
+ * Authentication/authorization errors
+ */
+export class AuthError extends VizzlyError {
+    constructor(message: any, context?: {});
+}
+/**
+ * Network/connection errors
+ */
+export class NetworkError extends VizzlyError {
+    constructor(message: any, context?: {});
+}
+/**
+ * Upload-related errors
+ */
+export class UploadError extends VizzlyError {
+    constructor(message: any, context?: {});
+}
+/**
+ * Screenshot-related errors
+ */
+export class ScreenshotError extends VizzlyError {
+    constructor(message: any, context?: {});
+}
+/**
+ * Build-related errors
+ */
+export class BuildError extends VizzlyError {
+    constructor(message: any, context?: {});
+}
+/**
+ * Timeout errors
+ */
+export class TimeoutError extends VizzlyError {
+    constructor(message: any, duration: any, context?: {});
+    duration: any;
+}
+/**
+ * Validation errors
+ */
+export class ValidationError extends VizzlyError {
+    constructor(message: any, errors?: any[], context?: {});
+    errors: any[];
+}

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+export { createVizzly } from "./sdk/index.js";
+export { createUploader } from "./services/uploader.js";
+export { createTDDService } from "./services/tdd-service.js";
+export { BaseService } from "./services/base-service.js";
+export { loadConfig } from "./utils/config-loader.js";
+export { createLogger } from "./utils/logger.js";
+export { defineConfig } from "./utils/config-helpers.js";
+export { UploadError } from "./errors/vizzly-error.js";
+export { vizzlyScreenshot, configure, setEnabled } from "./client/index.js";
+export { ServiceContainer, container } from "./container/index.js";

package/dist/types/index.js

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview Vizzly CLI type definitions
+ * Comprehensive JSDoc type definitions for IDE support
+ */
+
+/**
+ * @typedef {Object} VizzlyConfig
+ * @property {string} [apiKey] - API key for authentication
+ * @property {string} [apiUrl='https://vizzly.dev'] - API base URL
+ * @property {ServerConfig} [server] - Server configuration
+ * @property {BuildConfig} [build] - Build configuration
+ * @property {UploadConfig} [upload] - Upload configuration
+ * @property {ComparisonConfig} [comparison] - Comparison configuration
+ */
+
+/**
+ * @typedef {Object} ServerConfig
+ * @property {number} [port=3001] - Server port
+ * @property {string} [host='localhost'] - Server host
+ * @property {boolean} [https=false] - Use HTTPS
+ * @property {string} [certPath] - Path to SSL certificate
+ * @property {string} [keyPath] - Path to SSL key
+ * @property {string} [screenshotPath='/screenshot'] - Screenshot POST endpoint path
+ */
+
+/**
+ * @typedef {Object} BuildConfig
+ * @property {string} [name] - Build name
+ * @property {string} [branch] - Git branch
+ * @property {string} [commit] - Git commit SHA
+ * @property {string} [message] - Commit message
+ * @property {string} [environment='production'] - Environment name
+ * @property {Object.<string, any>} [metadata] - Additional metadata
+ */
+
+/**
+ * @typedef {Object} UploadConfig
+ * @property {string} [screenshotsDir='screenshots'] - Directory containing screenshots
+ * @property {number} [batchSize=50] - Upload batch size
+ * @property {number} [timeout=300000] - Upload timeout in ms
+ * @property {number} [retries=3] - Number of retries
+ * @property {boolean} [deduplication=true] - Enable deduplication
+ */
+
+/**
+ * @typedef {Object} ComparisonConfig
+ * @property {number} [threshold=0.1] - Default comparison threshold (0-1)
+ * @property {boolean} [ignoreAntialiasing=true] - Ignore antialiasing differences
+ * @property {boolean} [ignoreColors=false] - Ignore color differences
+ * @property {string} [diffColor='#ff0000'] - Color for diff highlighting
+ */
+
+/**
+ * @typedef {Object} Screenshot
+ * @property {string} name - Screenshot name
+ * @property {Buffer} image - Image buffer data
+ * @property {Object.<string, any>} [properties] - Additional properties
+ * @property {number} [threshold] - Comparison threshold override
+ * @property {string} [group] - Screenshot group/category
+ * @property {string[]} [tags] - Screenshot tags
+ */
+
+/**
+ * @typedef {Object} UploadOptions
+ * @property {string} screenshotsDir - Directory containing screenshots
+ * @property {string} [buildName] - Name for this build
+ * @property {string} [branch] - Git branch name
+ * @property {string} [commit] - Git commit SHA
+ * @property {string} [message] - Commit message
+ * @property {string} [environment='production'] - Environment name
+ * @property {number} [threshold] - Default comparison threshold
+ * @property {ProgressCallback} [onProgress] - Progress callback
+ */
+
+/**
+ * @typedef {Object} UploadResult
+ * @property {boolean} success - Whether upload succeeded
+ * @property {string} [buildId] - Build ID if successful
+ * @property {string} [url] - Build URL if available
+ * @property {UploadStats} stats - Upload statistics
+ * @property {string} [error] - Error message if failed
+ */
+
+/**
+ * @typedef {Object} UploadStats
+ * @property {number} total - Total files found
+ * @property {number} uploaded - Files uploaded
+ * @property {number} skipped - Files skipped (duplicates)
+ * @property {number} failed - Files failed to upload
+ */
+
+/**
+ * @typedef {Object} ProgressEvent
+ * @property {'scanning'|'processing'|'deduplication'|'uploading'|'completed'|'error'} phase - Current phase
+ * @property {number} [current] - Current item being processed
+ * @property {number} [total] - Total items to process
+ * @property {string} [message] - Progress message
+ * @property {number} [toUpload] - Files to upload (deduplication phase)
+ * @property {number} [existing] - Existing files (deduplication phase)
+ * @property {string} [buildId] - Build ID (completed phase)
+ * @property {string} [url] - Build URL (completed phase)
+ */
+
+/**
+ * @callback ProgressCallback
+ * @param {ProgressEvent} event - Progress event
+ * @returns {void}
+ */
+
+/**
+ * @typedef {Object} TDDOptions
+ * @property {string} [baselineDir='baseline'] - Baseline screenshots directory
+ * @property {string} [currentDir='screenshots'] - Current screenshots directory
+ * @property {string} [diffDir='diffs'] - Diff output directory
+ * @property {number} [threshold=0.1] - Comparison threshold
+ * @property {boolean} [failOnDifference=true] - Fail on any difference
+ * @property {boolean} [updateBaseline=false] - Update baseline on difference
+ */
+
+/**
+ * @typedef {Object} ComparisonResult
+ * @property {string} name - Screenshot name
+ * @property {boolean} passed - Whether comparison passed
+ * @property {number} [difference] - Difference percentage (0-1)
+ * @property {string} [diffPath] - Path to diff image
+ * @property {string} [error] - Error message if comparison failed
+ */
+
+/**
+ * @typedef {Object} BuildInfo
+ * @property {string} id - Build ID
+ * @property {string} name - Build name
+ * @property {'pending'|'processing'|'completed'|'failed'} status - Build status
+ * @property {string} branch - Git branch
+ * @property {string} [commit] - Git commit SHA
+ * @property {string} environment - Environment name
+ * @property {Date} createdAt - Creation timestamp
+ * @property {Date} [completedAt] - Completion timestamp
+ * @property {number} screenshotCount - Number of screenshots
+ * @property {Object.<string, any>} [metadata] - Additional metadata
+ */
+
+/**
+ * @typedef {Object} CLIOptions
+ * @property {boolean} [verbose=false] - Enable verbose logging
+ * @property {string} [logLevel='info'] - Log level
+ * @property {boolean} [quiet=false] - Suppress all output
+ * @property {boolean} [json=false] - Output JSON instead of text
+ * @property {string} [config] - Path to config file
+ */
+
+// Export types for use in other files
+export default {};

package/dist/types/screenshot-wrapper.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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: any): (overrideConfig?: {}) => any;

package/dist/types/sdk/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Create a new Vizzly instance with custom configuration
+ *
+ * @param {import('../types').VizzlyConfig} [config] - Configuration options
+ * @returns {Promise<VizzlySDK>} Configured Vizzly SDK instance
+ *
+ * @example
+ * // Create with custom config
+ * import { createVizzly } from '@vizzly-testing/cli/sdk';
+ *
+ * const vizzly = await createVizzly({
+ *   apiKey: process.env.VIZZLY_TOKEN,
+ *   apiUrl: 'https://vizzly.dev',
+ *   server: {
+ *     port: 3003,
+ *     enabled: true
+ *   }
+ * });
+ *
+ * // Start the server
+ * await vizzly.start();
+ *
+ * // Take screenshots
+ * const screenshot = await getScreenshotSomehow();
+ * await vizzly.screenshot('my-test', screenshot);
+ *
+ * // Upload results
+ * const result = await vizzly.upload();
+ * console.log(`Build URL: ${result.url}`);
+ *
+ * // Cleanup
+ * await vizzly.stop();
+ */
+export function createVizzly(config?: import("../types").VizzlyConfig, options?: {}): Promise<VizzlySDK>;
+/**
+ * @typedef {Object} VizzlySDK
+ * @property {Function} start - Start the Vizzly server
+ * @property {Function} stop - Stop the Vizzly server
+ * @property {Function} screenshot - Capture a screenshot
+ * @property {Function} upload - Upload screenshots to Vizzly
+ * @property {Function} compare - Run local comparison (TDD mode)
+ * @property {Function} getConfig - Get current configuration
+ * @property {Function} on - Subscribe to events
+ * @property {Function} off - Unsubscribe from events
+ */
+/**
+ * VizzlySDK class implementation
+ * @class
+ * @extends {EventEmitter}
+ */
+export class VizzlySDK extends EventEmitter<[never]> {
+    /**
+     * @param {import('../types').VizzlyConfig} config - Configuration
+     * @param {import('../utils/logger').Logger} logger - Logger instance
+     * @param {Object} services - Service instances
+     */
+    constructor(config: import("../types").VizzlyConfig, logger: import("../utils/logger").Logger, services: any);
+    config: import("../types").VizzlyConfig;
+    logger: import("../utils/logger.js").Logger;
+    services: any;
+    server: ScreenshotServer;
+    currentBuildId: any;
+    /**
+     * Stop the Vizzly server
+     * @returns {Promise<void>}
+     */
+    stop(): Promise<void>;
+    /**
+     * Get current configuration
+     * @returns {Object} Current config
+     */
+    getConfig(): any;
+    /**
+     * Start the Vizzly server
+     * @returns {Promise<{port: number, url: string}>} Server information
+     */
+    start(): Promise<{
+        port: number;
+        url: string;
+    }>;
+    /**
+     * Capture a screenshot
+     * @param {string} name - Screenshot name
+     * @param {Buffer} imageBuffer - Image data
+     * @param {import('../types').ScreenshotOptions} [options] - Options
+     * @returns {Promise<void>}
+     */
+    screenshot(name: string, imageBuffer: Buffer, options?: import("../types").ScreenshotOptions): Promise<void>;
+    /**
+     * Upload all captured screenshots
+     * @param {import('../types').UploadOptions} [options] - Upload options
+     * @returns {Promise<import('../types').UploadResult>} Upload result
+     */
+    upload(options?: import("../types").UploadOptions): Promise<import("../types").UploadResult>;
+    /**
+     * Run local comparison in TDD mode
+     * @param {string} name - Screenshot name
+     * @param {Buffer} imageBuffer - Current image
+     * @returns {Promise<import('../types').ComparisonResult>} Comparison result
+     */
+    compare(name: string, imageBuffer: Buffer): Promise<import("../types").ComparisonResult>;
+}
+export { loadConfig } from "../utils/config-loader.js";
+export { createLogger } from "../utils/logger.js";
+export { createUploader } from "../services/uploader.js";
+export { createTDDService } from "../services/tdd-service.js";
+import { EventEmitter } from 'events';
+import { ScreenshotServer } from '../services/screenshot-server.js';

package/dist/types/server/index.d.ts

@@ -0,0 +1,38 @@
+export class VizzlyServer {
+    constructor({ port, config, tddMode, baselineBuild, baselineComparison, workingDir, buildId, vizzlyApi, buildInfo, emitter, }: {
+        port: any;
+        config: any;
+        tddMode?: boolean;
+        baselineBuild: any;
+        baselineComparison: any;
+        workingDir: any;
+        buildId?: any;
+        vizzlyApi?: any;
+        buildInfo?: any;
+        emitter?: any;
+    });
+    port: any;
+    config: any;
+    builds: Map<any, any>;
+    server: import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
+    tddMode: boolean;
+    baselineBuild: any;
+    baselineComparison: any;
+    tddService: TddService;
+    buildId: any;
+    vizzlyApi: any;
+    buildInfo: any;
+    emitter: any;
+    vizzlyDisabled: boolean;
+    start(): Promise<any>;
+    handleRequest(req: any, res: any): Promise<void>;
+    handleScreenshot(req: any, res: any): Promise<void>;
+    parseRequestBody(req: any): Promise<any>;
+    stop(): Promise<any>;
+    createBuild(options: any): Promise<`${string}-${string}-${string}-${string}-${string}`>;
+    getScreenshotCount(buildId: any): any;
+    getTotalScreenshotCount(): number;
+    finishBuild(buildId: any): Promise<any>;
+    cleanupBuild(buildId: any): Promise<void>;
+}
+import { TddService } from '../services/tdd-service.js';

package/dist/types/services/api-service.d.ts

@@ -0,0 +1,77 @@
+/**
+ * ApiService class for direct API communication
+ */
+export class ApiService {
+    constructor(options?: {});
+    baseUrl: any;
+    token: any;
+    userAgent: string;
+    /**
+     * Make an API request
+     * @param {string} endpoint - API endpoint
+     * @param {Object} options - Fetch options
+     * @returns {Promise<Object>} Response data
+     */
+    request(endpoint: string, options?: any): Promise<any>;
+    /**
+     * Get build information
+     * @param {string} buildId - Build ID
+     * @param {string} include - Optional include parameter (e.g., 'screenshots')
+     * @returns {Promise<Object>} Build data
+     */
+    getBuild(buildId: string, include?: string): Promise<any>;
+    /**
+     * Get comparison information
+     * @param {string} comparisonId - Comparison ID
+     * @returns {Promise<Object>} Comparison data
+     */
+    getComparison(comparisonId: string): Promise<any>;
+    /**
+     * Get builds for a project
+     * @param {Object} filters - Filter options
+     * @returns {Promise<Array>} List of builds
+     */
+    getBuilds(filters?: any): Promise<any[]>;
+    /**
+     * Create a new build
+     * @param {Object} metadata - Build metadata
+     * @returns {Promise<Object>} Created build data
+     */
+    createBuild(metadata: any): Promise<any>;
+    /**
+     * Check if SHAs already exist on the server
+     * @param {string[]} shas - Array of SHA256 hashes to check
+     * @returns {Promise<string[]>} Array of existing SHAs
+     */
+    checkShas(shas: string[]): Promise<string[]>;
+    /**
+     * Upload a screenshot with SHA checking
+     * @param {string} buildId - Build ID
+     * @param {string} name - Screenshot name
+     * @param {Buffer} buffer - Screenshot data
+     * @param {Object} metadata - Additional metadata
+     * @returns {Promise<Object>} Upload result
+     */
+    uploadScreenshot(buildId: string, name: string, buffer: Buffer, metadata?: any): Promise<any>;
+    /**
+     * Update build status
+     * @param {string} buildId - Build ID
+     * @param {string} status - Build status (pending|running|completed|failed)
+     * @param {number} executionTimeMs - Execution time in milliseconds
+     * @returns {Promise<Object>} Updated build data
+     */
+    updateBuildStatus(buildId: string, status: string, executionTimeMs?: number): Promise<any>;
+    /**
+     * Finalize a build (convenience method)
+     * @param {string} buildId - Build ID
+     * @param {boolean} success - Whether the build succeeded
+     * @param {number} executionTimeMs - Execution time in milliseconds
+     * @returns {Promise<Object>} Finalized build data
+     */
+    finalizeBuild(buildId: string, success?: boolean, executionTimeMs?: number): Promise<any>;
+    /**
+     * Get token context (organization and project info)
+     * @returns {Promise<Object>} Token context data
+     */
+    getTokenContext(): Promise<any>;
+}