@vizzly-testing/cli 0.29.6 → 0.31.0

package/dist/tdd/tdd-service.js

@@ -22,7 +22,8 @@ import { generateBaselineFilename as defaultGenerateBaselineFilename, generateCo
 import { createEmptyBaselineMetadata as defaultCreateEmptyBaselineMetadata, loadBaselineMetadata as defaultLoadBaselineMetadata, saveBaselineMetadata as defaultSaveBaselineMetadata, upsertScreenshotInMetadata as defaultUpsertScreenshotInMetadata } from './metadata/baseline-metadata.js';
 import { loadHotspotMetadata as defaultLoadHotspotMetadata, saveHotspotMetadata as defaultSaveHotspotMetadata } from './metadata/hotspot-metadata.js';
 import { loadRegionMetadata as defaultLoadRegionMetadata, saveRegionMetadata as defaultSaveRegionMetadata } from './metadata/region-metadata.js';
-import { baselineExists as defaultBaselineExists, clearBaselineData as defaultClearBaselineData, getBaselinePath as defaultGetBaselinePath, getCurrentPath as defaultGetCurrentPath, getDiffPath as defaultGetDiffPath, initializeDirectories as defaultInitializeDirectories, saveBaseline as defaultSaveBaseline, saveCurrent as defaultSaveCurrent } from './services/baseline-manager.js';
+import { buildTddDependencyOps, resolveTddPaths, resolveTddWorkingDirectory } from './runtime-context.js';
+import { baselineExists as defaultBaselineExists, clearBaselineData as defaultClearBaselineData, clearRunData as defaultClearRunData, getBaselinePath as defaultGetBaselinePath, getCurrentPath as defaultGetCurrentPath, getDiffPath as defaultGetDiffPath, initializeDirectories as defaultInitializeDirectories, saveBaseline as defaultSaveBaseline, saveCurrent as defaultSaveCurrent } from './services/baseline-manager.js';
 import { buildErrorComparison as defaultBuildErrorComparison, buildFailedComparison as defaultBuildFailedComparison, buildNewComparison as defaultBuildNewComparison, buildPassedComparison as defaultBuildPassedComparison, compareImages as defaultCompareImages, isDimensionMismatchError as defaultIsDimensionMismatchError } from './services/comparison-service.js';
 import { buildResults as defaultBuildResults, getFailedComparisons as defaultGetFailedComparisons, getNewComparisons as defaultGetNewComparisons } from './services/result-service.js';
 
@@ -40,110 +41,79 @@ export function createTDDService(config, options = {}, deps = {}) {
 }
 export class TddService {
   constructor(config, workingDir = process.cwd(), setBaseline = false, authService = null, deps = {}) {
-    // Grouped dependencies with defaults
-    let {
-      // Core utilities
-      output = defaultOutput,
-      colors = defaultColors,
-      validatePathSecurity = defaultValidatePathSecurity,
-      initializeDirectories = defaultInitializeDirectories,
-      // File system operations
-      fs = {},
-      // API operations
-      api = {},
-      // Baseline metadata operations
-      metadata = {},
-      // Baseline file management
-      baseline = {},
-      // Screenshot comparison
-      comparison = {},
-      // Signature generation and security
-      signature = {},
-      // Result building
-      results = {},
-      // Other
-      calculateHotspotCoverage = defaultCalculateHotspotCoverage
-    } = deps;
-
-    // Merge grouped deps with defaults
-    let fsOps = {
-      existsSync: defaultExistsSync,
-      mkdirSync: defaultMkdirSync,
-      readFileSync: defaultReadFileSync,
-      writeFileSync: defaultWriteFileSync,
-      ...fs
-    };
-    let apiOps = {
-      createApiClient: defaultCreateApiClient,
-      getTddBaselines: defaultGetTddBaselines,
-      getBuilds: defaultGetBuilds,
-      getComparison: defaultGetComparison,
-      getBatchHotspots: defaultGetBatchHotspots,
-      fetchWithTimeout: defaultFetchWithTimeout,
-      getDefaultBranch: defaultGetDefaultBranch,
-      ...api
-    };
-    let metadataOps = {
-      loadBaselineMetadata: defaultLoadBaselineMetadata,
-      saveBaselineMetadata: defaultSaveBaselineMetadata,
-      createEmptyBaselineMetadata: defaultCreateEmptyBaselineMetadata,
-      upsertScreenshotInMetadata: defaultUpsertScreenshotInMetadata,
-      loadHotspotMetadata: defaultLoadHotspotMetadata,
-      saveHotspotMetadata: defaultSaveHotspotMetadata,
-      loadRegionMetadata: defaultLoadRegionMetadata,
-      saveRegionMetadata: defaultSaveRegionMetadata,
-      ...metadata
-    };
-    let baselineOps = {
-      baselineExists: defaultBaselineExists,
-      clearBaselineData: defaultClearBaselineData,
-      getBaselinePath: defaultGetBaselinePath,
-      getCurrentPath: defaultGetCurrentPath,
-      getDiffPath: defaultGetDiffPath,
-      saveBaseline: defaultSaveBaseline,
-      saveCurrent: defaultSaveCurrent,
-      ...baseline
-    };
-    let comparisonOps = {
-      compareImages: defaultCompareImages,
-      buildPassedComparison: defaultBuildPassedComparison,
-      buildNewComparison: defaultBuildNewComparison,
-      buildFailedComparison: defaultBuildFailedComparison,
-      buildErrorComparison: defaultBuildErrorComparison,
-      isDimensionMismatchError: defaultIsDimensionMismatchError,
-      ...comparison
-    };
-    let signatureOps = {
-      generateScreenshotSignature: defaultGenerateScreenshotSignature,
-      generateBaselineFilename: defaultGenerateBaselineFilename,
-      generateComparisonId: defaultGenerateComparisonId,
-      sanitizeScreenshotName: defaultSanitizeScreenshotName,
-      validateScreenshotProperties: defaultValidateScreenshotProperties,
-      safePath: defaultSafePath,
-      ...signature
-    };
-    let resultsOps = {
-      buildResults: defaultBuildResults,
-      getFailedComparisons: defaultGetFailedComparisons,
-      getNewComparisons: defaultGetNewComparisons,
-      ...results
+    let defaults = {
+      output: defaultOutput,
+      colors: defaultColors,
+      validatePathSecurity: defaultValidatePathSecurity,
+      initializeDirectories: defaultInitializeDirectories,
+      calculateHotspotCoverage: defaultCalculateHotspotCoverage,
+      fs: {
+        existsSync: defaultExistsSync,
+        mkdirSync: defaultMkdirSync,
+        readFileSync: defaultReadFileSync,
+        writeFileSync: defaultWriteFileSync
+      },
+      api: {
+        createApiClient: defaultCreateApiClient,
+        getTddBaselines: defaultGetTddBaselines,
+        getBuilds: defaultGetBuilds,
+        getComparison: defaultGetComparison,
+        getBatchHotspots: defaultGetBatchHotspots,
+        fetchWithTimeout: defaultFetchWithTimeout,
+        getDefaultBranch: defaultGetDefaultBranch
+      },
+      metadata: {
+        loadBaselineMetadata: defaultLoadBaselineMetadata,
+        saveBaselineMetadata: defaultSaveBaselineMetadata,
+        createEmptyBaselineMetadata: defaultCreateEmptyBaselineMetadata,
+        upsertScreenshotInMetadata: defaultUpsertScreenshotInMetadata,
+        loadHotspotMetadata: defaultLoadHotspotMetadata,
+        saveHotspotMetadata: defaultSaveHotspotMetadata,
+        loadRegionMetadata: defaultLoadRegionMetadata,
+        saveRegionMetadata: defaultSaveRegionMetadata
+      },
+      baseline: {
+        baselineExists: defaultBaselineExists,
+        clearBaselineData: defaultClearBaselineData,
+        clearRunData: defaultClearRunData,
+        getBaselinePath: defaultGetBaselinePath,
+        getCurrentPath: defaultGetCurrentPath,
+        getDiffPath: defaultGetDiffPath,
+        saveBaseline: defaultSaveBaseline,
+        saveCurrent: defaultSaveCurrent
+      },
+      comparison: {
+        compareImages: defaultCompareImages,
+        buildPassedComparison: defaultBuildPassedComparison,
+        buildNewComparison: defaultBuildNewComparison,
+        buildFailedComparison: defaultBuildFailedComparison,
+        buildErrorComparison: defaultBuildErrorComparison,
+        isDimensionMismatchError: defaultIsDimensionMismatchError
+      },
+      signature: {
+        generateScreenshotSignature: defaultGenerateScreenshotSignature,
+        generateBaselineFilename: defaultGenerateBaselineFilename,
+        generateComparisonId: defaultGenerateComparisonId,
+        sanitizeScreenshotName: defaultSanitizeScreenshotName,
+        validateScreenshotProperties: defaultValidateScreenshotProperties,
+        safePath: defaultSafePath
+      },
+      results: {
+        buildResults: defaultBuildResults,
+        getFailedComparisons: defaultGetFailedComparisons,
+        getNewComparisons: defaultGetNewComparisons
+      }
     };
-
-    // Store flattened dependencies for use in methods
-    this._deps = {
+    let {
+      runtimeDeps,
+      apiOps
+    } = buildTddDependencyOps(deps, defaults);
+    let {
       output,
-      colors,
       validatePathSecurity,
-      initializeDirectories,
-      calculateHotspotCoverage,
-      ...fsOps,
-      ...apiOps,
-      ...metadataOps,
-      ...baselineOps,
-      ...comparisonOps,
-      ...signatureOps,
-      ...resultsOps
-    };
+      initializeDirectories
+    } = runtimeDeps;
+    this._deps = runtimeDeps;
     this.config = config;
     this.setBaseline = setBaseline;
     this.authService = authService;
@@ -155,15 +125,8 @@ export class TddService {
     });
 
     // Validate and secure the working directory
-    try {
-      this.workingDir = validatePathSecurity(workingDir, workingDir);
-    } catch (error) {
-      output.error(`Invalid working directory: ${error.message}`);
-      throw new Error(`Working directory validation failed: ${error.message}`);
-    }
-
-    // Initialize directories using extracted module
-    let paths = initializeDirectories(this.workingDir);
+    this.workingDir = resolveTddWorkingDirectory(workingDir, validatePathSecurity, output);
+    let paths = resolveTddPaths(this.workingDir, initializeDirectories);
     this.baselinePath = paths.baselinePath;
     this.currentPath = paths.currentPath;
     this.diffPath = paths.diffPath;
@@ -171,7 +134,7 @@ export class TddService {
     // State
     this.baselineData = null;
     this.comparisons = [];
-    this.threshold = config.comparison?.threshold || 2.0;
+    this.threshold = config.comparison?.threshold ?? 2.0;
     this.minClusterSize = config.comparison?.minClusterSize ?? 2;
     this.signatureProperties = config.signatureProperties ?? [];
 
@@ -187,6 +150,12 @@ export class TddService {
       output.info('[vizzly] Baseline update mode - will overwrite existing baselines with new ones');
     }
   }
+  clearRunData() {
+    this._deps.clearRunData({
+      currentPath: this.currentPath,
+      diffPath: this.diffPath
+    });
+  }
 
   /**
    * Download baselines from cloud
@@ -915,7 +884,7 @@ export class TddService {
       return null;
     }
     this.baselineData = metadata;
-    this.threshold = metadata.threshold || this.threshold;
+    this.threshold = metadata.threshold ?? this.threshold;
     this.signatureProperties = metadata.signatureProperties || this.signatureProperties;
     if (this.signatureProperties.length > 0) {
       output.debug('tdd', `loaded signature properties: ${this.signatureProperties.join(', ')}`);

package/dist/types/client.d.ts

@@ -4,6 +4,40 @@
  * @module @vizzly-testing/cli/client
  */
 
+export type ClientLogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export const LOG_LEVELS: Readonly<Record<ClientLogLevel, number>>;
+
+/**
+ * Check whether client SDK output should log at the requested level.
+ */
+export function shouldLogClient(
+  level: string,
+  configuredLevel?: string
+): boolean;
+
+/**
+ * Auto-discover a local TDD server by searching for `.vizzly/server.json`.
+ */
+export function autoDiscoverTddServer(
+  startDir?: string,
+  deps?: {
+    exists?: (path: string) => boolean;
+    readFile?: (path: string, encoding: BufferEncoding) => string | Buffer;
+  }
+): string | null;
+
+/**
+ * Result returned by a successful screenshot capture.
+ */
+export interface ScreenshotResult {
+  success: boolean;
+  status?: 'passed' | 'failed' | 'new';
+  name?: string;
+  diffPercentage?: number;
+  [key: string]: unknown;
+}
+
 /**
  * Take a screenshot for visual regression testing
  *
@@ -38,8 +72,9 @@ export function vizzlyScreenshot(
     threshold?: number;
     minClusterSize?: number;
     fullPage?: boolean;
+    [key: string]: unknown;
   }
-): Promise<void>;
+): Promise<ScreenshotResult | null>;
 
 /**
  * Flush result summary returned by vizzlyFlush

package/dist/types/index.d.ts

@@ -77,6 +77,7 @@ export interface ScreenshotOptions {
   minClusterSize?: number;
   fullPage?: boolean;
   buildId?: string;
+  [key: string]: unknown;
 }
 
 export interface ScreenshotResult {
@@ -84,6 +85,7 @@ export interface ScreenshotResult {
   status?: 'passed' | 'failed' | 'new';
   name?: string;
   diffPercentage?: number;
+  [key: string]: unknown;
 }
 
 // ============================================================================
@@ -262,6 +264,12 @@ export class ValidationError extends VizzlyError {
 export interface VizzlySDKInstance extends EventEmitter {
   config: VizzlyConfig;
 
+  /** Reload file config and re-apply current in-memory overrides */
+  init(): Promise<VizzlyConfig>;
+
+  /** Merge new config values into the active SDK config */
+  updateConfig(newConfig: Partial<VizzlyConfig>): VizzlyConfig;
+
   /** Start the Vizzly server */
   start(): Promise<{ port: number; url: string }>;
 
@@ -286,6 +294,28 @@ export interface VizzlySDKInstance extends EventEmitter {
     name: string,
     imageBuffer: Buffer | string
   ): Promise<ComparisonResult>;
+
+  /** Create an uploader using the SDK config */
+  createUploader(options?: {
+    upload?: UploadConfig;
+    signal?: AbortSignal;
+    batchSize?: number;
+    timeout?: number;
+  }): Uploader;
+
+  /** Create a local TDD service using the SDK config */
+  createTDDService(options?: {
+    workingDir?: string;
+    setBaseline?: boolean;
+    authService?: unknown;
+  }): TddService;
+
+  /** Start a local TDD service */
+  startTDD(options?: {
+    workingDir?: string;
+    setBaseline?: boolean;
+    authService?: unknown;
+  }): Promise<unknown>;
 }
 
 export class VizzlySDK extends EventEmitter implements VizzlySDKInstance {
@@ -293,6 +323,8 @@ export class VizzlySDK extends EventEmitter implements VizzlySDKInstance {
 
   constructor(config: VizzlyConfig, services: unknown);
 
+  init(): Promise<VizzlyConfig>;
+  updateConfig(newConfig: Partial<VizzlyConfig>): VizzlyConfig;
   start(): Promise<{ port: number; url: string }>;
   stop(): Promise<void>;
   getConfig(): VizzlyConfig;
@@ -306,6 +338,22 @@ export class VizzlySDK extends EventEmitter implements VizzlySDKInstance {
     name: string,
     imageBuffer: Buffer | string
   ): Promise<ComparisonResult>;
+  createUploader(options?: {
+    upload?: UploadConfig;
+    signal?: AbortSignal;
+    batchSize?: number;
+    timeout?: number;
+  }): Uploader;
+  createTDDService(options?: {
+    workingDir?: string;
+    setBaseline?: boolean;
+    authService?: unknown;
+  }): TddService;
+  startTDD(options?: {
+    workingDir?: string;
+    setBaseline?: boolean;
+    authService?: unknown;
+  }): Promise<unknown>;
 }
 
 // ============================================================================
@@ -344,15 +392,8 @@ export interface TddService {
 }
 
 export interface Services {
-  apiService: unknown;
-  authService: unknown;
-  configService: unknown;
-  projectService: unknown;
-  uploader: Uploader;
-  buildManager: unknown;
-  serverManager: unknown;
-  tddService: TddService;
-  testRunner: unknown;
+  serverManager: ServerManager;
+  testRunner: TestRunnerService;
 }
 
 // ============================================================================
@@ -392,11 +433,47 @@ export interface PluginServerManager {
   stop(): Promise<void>;
 }
 
+/**
+ * Internal server manager returned by createServices().
+ */
+export interface ServerManager extends PluginServerManager {
+  /** Get current TDD results from the local server handler */
+  getTddResults(): Promise<TddResults | null>;
+  /** Current HTTP server facade, if running */
+  readonly server: unknown;
+}
+
+/**
+ * Internal TestRunner returned by createServices().
+ */
+export interface TestRunnerService extends PluginTestRunner {
+  /** Initialize daemon mode without running tests */
+  initialize(options: Record<string, unknown>): Promise<void>;
+  /** Run tests through the configured test command */
+  run(options: Record<string, unknown>): Promise<unknown>;
+  /** Cancel the active test process and stop the server */
+  cancel(): Promise<void>;
+}
+
+export interface PluginGitInfo {
+  branch: string;
+  commit: string | null;
+  message: string | null;
+  prNumber: number | null;
+  buildName: string;
+}
+
+export interface PluginGit {
+  /** Detect branch, commit, commit message, PR number, and build name */
+  detect(options?: { buildPrefix?: string }): Promise<PluginGitInfo>;
+}
+
 /**
  * Stable services interface for plugins.
  * This is the public API contract - internal services are NOT exposed.
  */
 export interface PluginServices {
+  git: PluginGit;
   testRunner: PluginTestRunner;
   serverManager: PluginServerManager;
 }
@@ -432,8 +509,6 @@ export interface PluginContext {
   services: PluginServices;
   /** Output utilities for logging */
   output: OutputUtils;
-  /** @deprecated Use output instead. Alias for backwards compatibility. */
-  logger: OutputUtils;
 }
 
 /** Create stable plugin services from internal services */
@@ -444,12 +519,31 @@ export function createPluginServices(services: Services): PluginServices;
 // ============================================================================
 
 export interface OutputUtils {
-  info(message: string): void;
-  warn(message: string): void;
-  error(message: string): void;
-  success(message: string): void;
-  debug(category: string, ...args: unknown[]): void;
-  configure(options: { verbose?: boolean }): void;
+  info(message: string, data?: Record<string, unknown>): void;
+  warn(message: string, data?: Record<string, unknown>): void;
+  error(
+    message: string,
+    error?: Error | null,
+    data?: Record<string, unknown>
+  ): void;
+  success(message: string, data?: Record<string, unknown>): void;
+  debug(
+    component: string,
+    message: string,
+    data?: Record<string, unknown>
+  ): void;
+  configure(options: OutputConfigureOptions): void;
+}
+
+export interface OutputConfigureOptions {
+  json?: boolean | string;
+  jsonFields?: string[] | null;
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+  verbose?: boolean;
+  color?: boolean;
+  silent?: boolean;
+  logFile?: string | null;
+  resetTimer?: boolean;
 }
 
 // ============================================================================
@@ -471,8 +565,9 @@ export function vizzlyScreenshot(
     threshold?: number;
     minClusterSize?: number;
     fullPage?: boolean;
+    [key: string]: unknown;
   }
-): Promise<void>;
+): Promise<ScreenshotResult | null>;
 
 /** Configure the Vizzly client */
 export function configure(config?: {
@@ -510,10 +605,7 @@ export function createTDDService(
 ): TddService;
 
 /** Create all services with dependencies */
-export function createServices(
-  config: VizzlyConfig,
-  command?: string
-): Services;
+export function createServices(config: VizzlyConfig): Services;
 
 /** Load configuration from file and environment */
 export function loadConfig(options?: { cwd?: string }): Promise<VizzlyConfig>;

package/dist/types/sdk.d.ts

@@ -8,16 +8,16 @@ import { EventEmitter } from 'node:events';
 
 // Re-export common types
 export {
-  VizzlyConfig,
-  ScreenshotOptions,
-  UploadOptions,
-  UploadResult,
+  BaselineData,
   ComparisonResult,
+  OutputUtils,
+  ScreenshotOptions,
   TddResults,
-  BaselineData,
-  Uploader,
   TddService,
-  OutputUtils,
+  Uploader,
+  UploadOptions,
+  UploadResult,
+  VizzlyConfig,
 } from './index';
 
 /**
@@ -41,6 +41,18 @@ export class VizzlySDK extends EventEmitter {
 
   constructor(config: import('./index').VizzlyConfig, services: unknown);
 
+  /**
+   * Reload file config and re-apply current in-memory overrides.
+   */
+  init(): Promise<import('./index').VizzlyConfig>;
+
+  /**
+   * Merge new config values into the active SDK config.
+   */
+  updateConfig(
+    newConfig: Partial<import('./index').VizzlyConfig>
+  ): import('./index').VizzlyConfig;
+
   /**
    * Start the Vizzly server
    * @returns Server information including port and URL
@@ -90,6 +102,34 @@ export class VizzlySDK extends EventEmitter {
     name: string,
     imageBuffer: Buffer | string
   ): Promise<import('./index').ComparisonResult>;
+
+  /**
+   * Create an uploader using the SDK config.
+   */
+  createUploader(options?: {
+    upload?: import('./index').UploadConfig;
+    signal?: AbortSignal;
+    batchSize?: number;
+    timeout?: number;
+  }): import('./index').Uploader;
+
+  /**
+   * Create a local TDD service using the SDK config.
+   */
+  createTDDService(options?: {
+    workingDir?: string;
+    setBaseline?: boolean;
+    authService?: unknown;
+  }): import('./index').TddService;
+
+  /**
+   * Start a local TDD service.
+   */
+  startTDD(options?: {
+    workingDir?: string;
+    setBaseline?: boolean;
+    authService?: unknown;
+  }): Promise<unknown>;
 }
 
 /**

package/dist/uploader/core.js

@@ -14,6 +14,7 @@ import { basename } from 'node:path';
 export const DEFAULT_BATCH_SIZE = 50;
 export const DEFAULT_SHA_CHECK_BATCH_SIZE = 100;
 export const DEFAULT_TIMEOUT = 30000; // 30 seconds
+export const DEFAULT_BUILD_POLL_INTERVAL = 1000; // 1 second
 
 // ============================================================================
 // Validation
@@ -363,8 +364,8 @@ export function resolveTimeout(options, uploadConfig) {
  * @param {number} timeout - Timeout in ms
  * @returns {boolean} True if timed out
  */
-export function isTimedOut(startTime, timeout) {
-  return Date.now() - startTime >= timeout;
+export function isTimedOut(startTime, timeout, now = Date.now()) {
+  return now - startTime >= timeout;
 }
 
 /**
@@ -372,8 +373,8 @@ export function isTimedOut(startTime, timeout) {
  * @param {number} startTime - Start timestamp
  * @returns {number} Elapsed time in ms
  */
-export function getElapsedTime(startTime) {
-  return Date.now() - startTime;
+export function getElapsedTime(startTime, now = Date.now()) {
+  return now - startTime;
 }
 
 /**