@vizzly-testing/cli 0.17.0 → 0.19.0

package/dist/services/uploader.js

@@ -3,14 +3,14 @@
  * Handles screenshot uploads to the Vizzly platform
  */
 
+import crypto from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { basename } from 'node:path';
 import { glob } from 'glob';
-import { readFile, stat } from 'fs/promises';
-import { basename } from 'path';
-import crypto from 'crypto';
+import { TimeoutError, UploadError, ValidationError } from '../errors/vizzly-error.js';
+import { getDefaultBranch } from '../utils/git.js';
 import * as output from '../utils/output.js';
 import { ApiService } from './api-service.js';
-import { getDefaultBranch } from '../utils/git.js';
-import { UploadError, TimeoutError, ValidationError } from '../errors/vizzly-error.js';
 const DEFAULT_BATCH_SIZE = 50;
 const DEFAULT_SHA_CHECK_BATCH_SIZE = 100;
 const DEFAULT_TIMEOUT = 30000; // 30 seconds
@@ -25,7 +25,7 @@ export function createUploader({
   command,
   upload: uploadConfig = {}
 } = {}, options = {}) {
-  let signal = options.signal || new AbortController().signal;
+  const signal = options.signal || new AbortController().signal;
   const api = new ApiService({
     baseUrl: apiUrl,
     token: apiKey,
@@ -160,7 +160,7 @@ export function createUploader({
       });
 
       // Re-throw if already a VizzlyError
-      if (error.name && error.name.includes('Error') && error.code) {
+      if (error.name?.includes('Error') && error.code) {
         throw error;
       }
 
@@ -304,7 +304,9 @@ async function checkExistingFiles(fileMetadata, api, signal, buildId) {
         existing = [],
         screenshots = []
       } = res || {};
-      existing.forEach(sha => existingShas.add(sha));
+      for (let sha of existing) {
+        existingShas.add(sha);
+      }
       allScreenshots.push(...screenshots);
     } catch (error) {
       // Continue without deduplication on error

package/dist/types/config.d.ts

@@ -20,7 +20,8 @@ export { VizzlyConfig } from './index';
  *     port: 47392
  *   },
  *   comparison: {
- *     threshold: 2.0  // CIEDE2000 Delta E (0=exact, 1=JND, 2=recommended)
+ *     threshold: 2.0,      // CIEDE2000 Delta E (0=exact, 1=JND, 2=recommended)
+ *     minClusterSize: 2    // Filter single-pixel noise (1=exact, 2=default, 3+=permissive)
  *   }
  * });
  */

package/dist/types/index.d.ts

@@ -3,7 +3,7 @@
  * @module @vizzly-testing/cli
  */
 
-import { EventEmitter } from 'events';
+import { EventEmitter } from 'node:events';
 
 // ============================================================================
 // Configuration Types
@@ -29,7 +29,17 @@ export interface UploadConfig {
 }
 
 export interface ComparisonConfig {
+  /** CIEDE2000 Delta E threshold (0=exact, 1=JND, 2=recommended default) */
   threshold?: number;
+  /**
+   * Minimum cluster size to count as a real difference.
+   * Filters out scattered single-pixel noise from rendering variance.
+   * - 1 = Exact matching (any different pixel counts)
+   * - 2 = Default (filters single isolated pixels as noise)
+   * - 3+ = More permissive (only larger clusters detected)
+   * @default 2
+   */
+  minClusterSize?: number;
 }
 
 export interface TddConfig {
@@ -341,6 +351,90 @@ export interface Services {
   testRunner: unknown;
 }
 
+// ============================================================================
+// Plugin API Types (Stable Contract)
+// ============================================================================
+
+/**
+ * Stable TestRunner interface for plugins.
+ * Only these methods are guaranteed to remain stable across minor versions.
+ */
+export interface PluginTestRunner {
+  /** Listen for a single event emission */
+  once(event: string, callback: (...args: unknown[]) => void): void;
+  /** Subscribe to events */
+  on(event: string, callback: (...args: unknown[]) => void): void;
+  /** Unsubscribe from events */
+  off(event: string, callback: (...args: unknown[]) => void): void;
+  /** Create a new build and return the build ID */
+  createBuild(options: BuildOptions, isTddMode: boolean): Promise<string>;
+  /** Finalize a build after all screenshots are captured */
+  finalizeBuild(
+    buildId: string,
+    isTddMode: boolean,
+    success: boolean,
+    executionTime: number
+  ): Promise<void>;
+}
+
+/**
+ * Stable ServerManager interface for plugins.
+ * Only these methods are guaranteed to remain stable across minor versions.
+ */
+export interface PluginServerManager {
+  /** Start the screenshot server */
+  start(buildId: string, tddMode: boolean, setBaseline: boolean): Promise<void>;
+  /** Stop the screenshot server */
+  stop(): Promise<void>;
+}
+
+/**
+ * Stable services interface for plugins.
+ * This is the public API contract - internal services are NOT exposed.
+ */
+export interface PluginServices {
+  testRunner: PluginTestRunner;
+  serverManager: PluginServerManager;
+}
+
+/**
+ * Build options for createBuild()
+ */
+export interface BuildOptions {
+  port?: number;
+  timeout?: number;
+  buildName?: string;
+  branch?: string;
+  commit?: string;
+  message?: string;
+  environment?: string;
+  threshold?: number;
+  eager?: boolean;
+  allowNoToken?: boolean;
+  wait?: boolean;
+  uploadAll?: boolean;
+  pullRequestNumber?: string;
+  parallelId?: string;
+}
+
+/**
+ * Context object passed to plugin register() function.
+ * This is the stable plugin API contract.
+ */
+export interface PluginContext {
+  /** Merged Vizzly configuration */
+  config: VizzlyConfig;
+  /** Stable services for plugins */
+  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 */
+export function createPluginServices(services: Services): PluginServices;
+
 // ============================================================================
 // Output Utilities
 // ============================================================================

package/dist/types/sdk.d.ts

@@ -4,7 +4,7 @@
  * @module @vizzly-testing/cli/sdk
  */
 
-import { EventEmitter } from 'events';
+import { EventEmitter } from 'node:events';
 
 // Re-export common types
 export {

package/dist/utils/browser.js

@@ -2,8 +2,8 @@
  * Browser utilities for opening URLs
  */
 
-import { execFile } from 'child_process';
-import { platform } from 'os';
+import { execFile } from 'node:child_process';
+import { platform } from 'node:os';
 
 /**
  * Open a URL in the default browser
@@ -14,7 +14,7 @@ export async function openBrowser(url) {
   return new Promise(resolve => {
     let command;
     let args;
-    let os = platform();
+    const os = platform();
     switch (os) {
       case 'darwin':
         // macOS

package/dist/utils/build-history.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, writeFileSync, readdirSync, rmSync } from 'fs';
-import { join } from 'path';
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 
 /**
  * Archive a build to history directory
@@ -11,7 +11,7 @@ import { join } from 'path';
  * @param {number} maxHistory - Maximum number of builds to keep (default: 3)
  */
 export function archiveBuild(workingDir, buildId, builds, comparisons, summary, maxHistory = 3) {
-  let historyDir = join(workingDir, '.vizzly', 'history');
+  const historyDir = join(workingDir, '.vizzly', 'history');
 
   // Create history directory if it doesn't exist
   if (!existsSync(historyDir)) {
@@ -21,13 +21,13 @@ export function archiveBuild(workingDir, buildId, builds, comparisons, summary,
   }
 
   // Save current build to history
-  let buildDir = join(historyDir, buildId);
+  const buildDir = join(historyDir, buildId);
   if (!existsSync(buildDir)) {
     mkdirSync(buildDir, {
       recursive: true
     });
   }
-  let buildData = {
+  const buildData = {
     buildId,
     timestamp: Date.now(),
     builds,
@@ -46,20 +46,20 @@ export function archiveBuild(workingDir, buildId, builds, comparisons, summary,
  * @returns {Array} Array of build metadata
  */
 export function getArchivedBuilds(workingDir) {
-  let historyDir = join(workingDir, '.vizzly', 'history');
+  const historyDir = join(workingDir, '.vizzly', 'history');
   if (!existsSync(historyDir)) {
     return [];
   }
   try {
-    let buildDirs = readdirSync(historyDir, {
+    const buildDirs = readdirSync(historyDir, {
       withFileTypes: true
     }).filter(dirent => dirent.isDirectory()).map(dirent => dirent.name).sort().reverse(); // Newest first
 
     return buildDirs.map(buildId => {
-      let reportPath = join(historyDir, buildId, 'report.json');
+      const reportPath = join(historyDir, buildId, 'report.json');
       if (existsSync(reportPath)) {
         try {
-          let data = JSON.parse(require('fs').readFileSync(reportPath, 'utf8'));
+          const data = JSON.parse(require('node:fs').readFileSync(reportPath, 'utf8'));
           return {
             buildId: data.buildId,
             timestamp: data.timestamp,
@@ -82,15 +82,15 @@ export function getArchivedBuilds(workingDir) {
  */
 function cleanupOldBuilds(historyDir, maxHistory) {
   try {
-    let buildDirs = readdirSync(historyDir, {
+    const buildDirs = readdirSync(historyDir, {
       withFileTypes: true
     }).filter(dirent => dirent.isDirectory()).map(dirent => dirent.name).sort().reverse(); // Newest first
 
     // Remove builds beyond maxHistory
     if (buildDirs.length > maxHistory) {
-      let toRemove = buildDirs.slice(maxHistory);
+      const toRemove = buildDirs.slice(maxHistory);
       toRemove.forEach(buildId => {
-        let buildDir = join(historyDir, buildId);
+        const buildDir = join(historyDir, buildId);
         rmSync(buildDir, {
           recursive: true,
           force: true

package/dist/utils/config-loader.js

@@ -1,10 +1,10 @@
+import { resolve } from 'node:path';
 import { cosmiconfigSync } from 'cosmiconfig';
-import { resolve } from 'path';
-import { getApiToken, getApiUrl, getParallelId } from './environment-config.js';
 import { validateVizzlyConfigWithDefaults } from './config-schema.js';
+import { getApiToken, getApiUrl, getParallelId } from './environment-config.js';
 import { getProjectMapping } from './global-config.js';
 import * as output from './output.js';
-let DEFAULT_CONFIG = {
+const DEFAULT_CONFIG = {
   // API Configuration
   apiKey: undefined,
   // Will be set from env, global config, or CLI overrides
@@ -38,19 +38,19 @@ let DEFAULT_CONFIG = {
 };
 export async function loadConfig(configPath = null, cliOverrides = {}) {
   // 1. Load from config file using cosmiconfig
-  let explorer = cosmiconfigSync('vizzly');
-  let result = configPath ? explorer.load(configPath) : explorer.search();
+  const explorer = cosmiconfigSync('vizzly');
+  const result = configPath ? explorer.load(configPath) : explorer.search();
   let fileConfig = {};
-  if (result && result.config) {
+  if (result?.config) {
     // Handle ESM default export (cosmiconfig wraps it in { default: {...} })
     fileConfig = result.config.default || result.config;
   }
 
   // 2. Validate config file using Zod schema
-  let validatedFileConfig = validateVizzlyConfigWithDefaults(fileConfig);
+  const validatedFileConfig = validateVizzlyConfigWithDefaults(fileConfig);
 
   // Create a proper clone of the default config to avoid shared object references
-  let config = {
+  const config = {
     ...DEFAULT_CONFIG,
     server: {
       ...DEFAULT_CONFIG.server
@@ -75,9 +75,9 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
 
   // 3. Check project mapping for current directory (if no CLI flag)
   if (!cliOverrides.token) {
-    let currentDir = process.cwd();
-    let projectMapping = await getProjectMapping(currentDir);
-    if (projectMapping && projectMapping.token) {
+    const currentDir = process.cwd();
+    const projectMapping = await getProjectMapping(currentDir);
+    if (projectMapping?.token) {
       // Handle both string tokens and token objects (backward compatibility)
       let token;
       if (typeof projectMapping.token === 'string') {
@@ -99,9 +99,9 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
   }
 
   // 4. Override with environment variables (higher priority than fallbacks)
-  let envApiKey = getApiToken();
-  let envApiUrl = getApiUrl();
-  let envParallelId = getParallelId();
+  const envApiKey = getApiToken();
+  const envApiUrl = getApiUrl();
+  const envParallelId = getParallelId();
   if (envApiKey) {
     config.apiKey = envApiKey;
     output.debug('Using API token from environment');
@@ -159,7 +159,7 @@ function applyCLIOverrides(config, cliOverrides = {}) {
   if (cliOverrides.allowNoToken !== undefined) config.allowNoToken = cliOverrides.allowNoToken;
 }
 function mergeConfig(target, source) {
-  for (let key in source) {
+  for (const key in source) {
     if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
       if (!target[key]) target[key] = {};
       mergeConfig(target[key], source[key]);
@@ -169,7 +169,7 @@ function mergeConfig(target, source) {
   }
 }
 export function getScreenshotPaths(config) {
-  let screenshotsDir = config.upload?.screenshotsDir || './screenshots';
-  let paths = Array.isArray(screenshotsDir) ? screenshotsDir : [screenshotsDir];
+  const screenshotsDir = config.upload?.screenshotsDir || './screenshots';
+  const paths = Array.isArray(screenshotsDir) ? screenshotsDir : [screenshotsDir];
   return paths.map(p => resolve(process.cwd(), p));
 }

package/dist/utils/config-schema.js

@@ -8,7 +8,7 @@ import { z } from 'zod';
 /**
  * Server configuration schema
  */
-let serverSchema = z.object({
+const serverSchema = z.object({
   port: z.number().int().positive().default(47392),
   timeout: z.number().int().positive().default(30000)
 });
@@ -16,7 +16,7 @@ let serverSchema = z.object({
 /**
  * Build configuration schema
  */
-let buildSchema = z.object({
+const buildSchema = z.object({
   name: z.string().default('Build {timestamp}'),
   environment: z.string().default('test'),
   branch: z.string().optional(),
@@ -27,7 +27,7 @@ let buildSchema = z.object({
 /**
  * Upload configuration schema
  */
-let uploadSchema = z.object({
+const uploadSchema = z.object({
   screenshotsDir: z.union([z.string(), z.array(z.string())]).default('./screenshots'),
   batchSize: z.number().int().positive().default(10),
   timeout: z.number().int().positive().default(30000)
@@ -37,14 +37,14 @@ let uploadSchema = z.object({
  * Comparison configuration schema
  * threshold: CIEDE2000 Delta E units (0.0 = exact, 1.0 = JND, 2.0 = recommended, 3.0+ = permissive)
  */
-let comparisonSchema = z.object({
+const comparisonSchema = z.object({
   threshold: z.number().min(0).default(2.0)
 });
 
 /**
  * TDD configuration schema
  */
-let tddSchema = z.object({
+const tddSchema = z.object({
   openReport: z.boolean().default(false)
 });
 
@@ -52,7 +52,7 @@ let tddSchema = z.object({
  * Core Vizzly configuration schema
  * Allows plugin-specific keys with passthrough for extensibility
  */
-export let vizzlyConfigSchema = z.object({
+export const vizzlyConfigSchema = z.object({
   // Core Vizzly config
   apiKey: z.string().optional(),
   apiUrl: z.string().url().optional(),

package/dist/utils/environment-config.js

@@ -3,6 +3,16 @@
  * Centralized access to environment variables with proper defaults
  */
 
+/**
+ * Get the Vizzly home directory from environment
+ * Used to override the default ~/.vizzly directory for storing auth, project mappings, etc.
+ * Useful for development (separate dev/prod configs) or testing (isolated test configs)
+ * @returns {string|undefined} Custom home directory path
+ */
+export function getVizzlyHome() {
+  return process.env.VIZZLY_HOME;
+}
+
 /**
  * Get API token from environment
  * @returns {string|undefined} API token
@@ -89,6 +99,7 @@ export function setVizzlyEnabled(enabled) {
  */
 export function getAllEnvironmentConfig() {
   return {
+    home: getVizzlyHome(),
     apiToken: getApiToken(),
     apiUrl: getApiUrl(),
     logLevel: getLogLevel(),

package/dist/utils/fetch-utils.js

@@ -1,6 +1,6 @@
 function fetchWithTimeout(url, opts = {}, ms = 300000) {
-  let ctrl = new AbortController();
-  let id = setTimeout(() => ctrl.abort(), ms);
+  const ctrl = new AbortController();
+  const id = setTimeout(() => ctrl.abort(), ms);
   return fetch(url, {
     ...opts,
     signal: ctrl.signal

package/dist/utils/file-helpers.js

@@ -3,8 +3,8 @@
  * @description Utilities for handling file-based screenshot inputs
  */
 
-import { existsSync, readFileSync } from 'fs';
-import { resolve } from 'path';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { VizzlyError } from '../errors/vizzly-error.js';
 
 /**

package/dist/utils/git.js

@@ -1,5 +1,5 @@
-import { exec } from 'child_process';
-import { promisify } from 'util';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
 import { getBranch as getCIBranch, getCommit as getCICommit, getCommitMessage as getCICommitMessage, getPullRequestNumber } from './ci-env.js';
 const execAsync = promisify(exec);
 export async function getCommonAncestor(commit1, commit2, cwd = process.cwd()) {
@@ -55,10 +55,7 @@ async function getCurrentBranchFallback(cwd = process.cwd()) {
         cwd
       });
       return branch;
-    } catch {
-      // Branch doesn't exist, try next one
-      continue;
-    }
+    } catch {}
   }
 
   // If none of the common branches exist, try to get any local branch

package/dist/utils/global-config.js

@@ -3,17 +3,20 @@
  * Manages ~/.vizzly/config.json for storing authentication tokens
  */
 
-import { homedir } from 'os';
-import { join, dirname, parse } from 'path';
-import { readFile, writeFile, mkdir, chmod } from 'fs/promises';
-import { existsSync } from 'fs';
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, parse } from 'node:path';
 import * as output from './output.js';
 
 /**
  * Get the path to the global Vizzly directory
- * @returns {string} Path to ~/.vizzly
+ * @returns {string} Path to VIZZLY_HOME or ~/.vizzly
  */
 export function getGlobalConfigDir() {
+  if (process.env.VIZZLY_HOME) {
+    return process.env.VIZZLY_HOME;
+  }
   return join(homedir(), '.vizzly');
 }
 
@@ -30,7 +33,7 @@ export function getGlobalConfigPath() {
  * @returns {Promise<void>}
  */
 async function ensureGlobalConfigDir() {
-  let dir = getGlobalConfigDir();
+  const dir = getGlobalConfigDir();
   if (!existsSync(dir)) {
     await mkdir(dir, {
       recursive: true,
@@ -45,11 +48,11 @@ async function ensureGlobalConfigDir() {
  */
 export async function loadGlobalConfig() {
   try {
-    let configPath = getGlobalConfigPath();
+    const configPath = getGlobalConfigPath();
     if (!existsSync(configPath)) {
       return {};
     }
-    let content = await readFile(configPath, 'utf-8');
+    const content = await readFile(configPath, 'utf-8');
     return JSON.parse(content);
   } catch (error) {
     // If file doesn't exist or is corrupted, return empty config
@@ -70,8 +73,8 @@ export async function loadGlobalConfig() {
  */
 export async function saveGlobalConfig(config) {
   await ensureGlobalConfigDir();
-  let configPath = getGlobalConfigPath();
-  let content = JSON.stringify(config, null, 2);
+  const configPath = getGlobalConfigPath();
+  const content = JSON.stringify(config, null, 2);
 
   // Write file with secure permissions (owner read/write only)
   await writeFile(configPath, content, {
@@ -102,7 +105,7 @@ export async function clearGlobalConfig() {
  * @returns {Promise<Object|null>} Token object with accessToken, refreshToken, expiresAt, user, or null if not found
  */
 export async function getAuthTokens() {
-  let config = await loadGlobalConfig();
+  const config = await loadGlobalConfig();
   if (!config.auth || !config.auth.accessToken) {
     return null;
   }
@@ -115,7 +118,7 @@ export async function getAuthTokens() {
  * @returns {Promise<void>}
  */
 export async function saveAuthTokens(auth) {
-  let config = await loadGlobalConfig();
+  const config = await loadGlobalConfig();
   config.auth = {
     accessToken: auth.accessToken,
     refreshToken: auth.refreshToken,
@@ -130,7 +133,7 @@ export async function saveAuthTokens(auth) {
  * @returns {Promise<void>}
  */
 export async function clearAuthTokens() {
-  let config = await loadGlobalConfig();
+  const config = await loadGlobalConfig();
   delete config.auth;
   await saveGlobalConfig(config);
 }
@@ -140,18 +143,18 @@ export async function clearAuthTokens() {
  * @returns {Promise<boolean>} True if valid tokens exist
  */
 export async function hasValidTokens() {
-  let auth = await getAuthTokens();
+  const auth = await getAuthTokens();
   if (!auth || !auth.accessToken) {
     return false;
   }
 
   // Check if token is expired
   if (auth.expiresAt) {
-    let expiresAt = new Date(auth.expiresAt);
-    let now = new Date();
+    const expiresAt = new Date(auth.expiresAt);
+    const now = new Date();
 
     // Consider expired if within 5 minutes of expiry
-    let bufferMs = 5 * 60 * 1000;
+    const bufferMs = 5 * 60 * 1000;
     if (now.getTime() >= expiresAt.getTime() - bufferMs) {
       return false;
     }
@@ -164,7 +167,7 @@ export async function hasValidTokens() {
  * @returns {Promise<string|null>} Access token or null
  */
 export async function getAccessToken() {
-  let auth = await getAuthTokens();
+  const auth = await getAuthTokens();
   return auth?.accessToken || null;
 }
 
@@ -175,14 +178,14 @@ export async function getAccessToken() {
  * @returns {Promise<Object|null>} Project data or null
  */
 export async function getProjectMapping(directoryPath) {
-  let config = await loadGlobalConfig();
+  const config = await loadGlobalConfig();
   if (!config.projects) {
     return null;
   }
 
   // Walk up the directory tree looking for a mapping
   let currentPath = directoryPath;
-  let {
+  const {
     root
   } = parse(currentPath);
   while (currentPath !== root) {
@@ -191,7 +194,7 @@ export async function getProjectMapping(directoryPath) {
     }
 
     // Move to parent directory
-    let parentPath = dirname(currentPath);
+    const parentPath = dirname(currentPath);
     if (parentPath === currentPath) {
       // We've reached the root
       break;
@@ -211,7 +214,7 @@ export async function getProjectMapping(directoryPath) {
  * @param {string} projectData.projectName - Project name
  */
 export async function saveProjectMapping(directoryPath, projectData) {
-  let config = await loadGlobalConfig();
+  const config = await loadGlobalConfig();
   if (!config.projects) {
     config.projects = {};
   }
@@ -227,7 +230,7 @@ export async function saveProjectMapping(directoryPath, projectData) {
  * @returns {Promise<Object>} Map of directory paths to project data
  */
 export async function getProjectMappings() {
-  let config = await loadGlobalConfig();
+  const config = await loadGlobalConfig();
   return config.projects || {};
 }
 
@@ -236,8 +239,8 @@ export async function getProjectMappings() {
  * @param {string} directoryPath - Absolute path to project directory
  */
 export async function deleteProjectMapping(directoryPath) {
-  let config = await loadGlobalConfig();
-  if (config.projects && config.projects[directoryPath]) {
+  const config = await loadGlobalConfig();
+  if (config.projects?.[directoryPath]) {
     delete config.projects[directoryPath];
     await saveGlobalConfig(config);
   }