@vizzly-testing/cli 0.34.0 → 0.35.0

package/dist/types/index.d.ts

@@ -24,7 +24,9 @@ export interface BuildConfig {
 
 export interface UploadConfig {
   screenshotsDir?: string | string[];
+  /** Batch size used when uploading screenshots. */
   batchSize?: number;
+  /** Timeout in milliseconds for waiting on build processing after upload. */
   timeout?: number;
 }
 
@@ -76,13 +78,22 @@ export interface ScreenshotOptions {
   threshold?: number;
   minClusterSize?: number;
   fullPage?: boolean;
+  /** Transport-only build ID used to route the request. */
   buildId?: string;
-  [key: string]: unknown;
+  /** Client-side HTTP timeout in milliseconds; not stored as metadata. */
+  requestTimeout?: number;
 }
 
 export interface ScreenshotResult {
   success: boolean;
-  status?: 'passed' | 'failed' | 'new';
+  status?:
+    | 'passed'
+    | 'failed'
+    | 'new'
+    | 'match'
+    | 'diff'
+    | 'baseline-updated'
+    | 'error';
   name?: string;
   diffPercentage?: number;
   [key: string]: unknown;
@@ -95,7 +106,13 @@ export interface ScreenshotResult {
 export interface ComparisonResult {
   id: string;
   name: string;
-  status: 'passed' | 'failed' | 'new' | 'error' | 'baseline-updated';
+  status:
+    | 'passed'
+    | 'failed'
+    | 'new'
+    | 'error'
+    | 'baseline-created'
+    | 'baseline-updated';
   baseline: string;
   current: string;
   diff: string | null;
@@ -150,7 +167,9 @@ export interface UploadOptions {
   message?: string;
   environment?: string;
   threshold?: number;
-  pullRequestNumber?: string;
+  minClusterSize?: number;
+  metadata?: Record<string, unknown>;
+  pullRequestNumber?: string | number;
   parallelId?: string;
   onProgress?: (progress: UploadProgress) => void;
 }
@@ -186,8 +205,10 @@ export interface BuildResult {
   status: 'completed' | 'failed' | 'pending';
   build: unknown;
   comparisons?: number;
+  totalComparisons: number;
   passedComparisons?: number;
   failedComparisons?: number;
+  newComparisons: number;
   url?: string;
 }
 
@@ -487,15 +508,19 @@ export interface BuildOptions {
   buildName?: string;
   branch?: string;
   commit?: string;
+  commit_sha?: string;
   message?: string;
+  commit_message?: string;
   environment?: string;
   threshold?: number;
   eager?: boolean;
   allowNoToken?: boolean;
   wait?: boolean;
   uploadAll?: boolean;
-  pullRequestNumber?: string;
+  pullRequestNumber?: string | number;
+  github_pull_request_number?: string | number;
   parallelId?: string;
+  parallel_id?: string;
 }
 
 /**
@@ -565,6 +590,8 @@ export function vizzlyScreenshot(
     threshold?: number;
     minClusterSize?: number;
     fullPage?: boolean;
+    requestTimeout?: number;
+    buildId?: string;
     [key: string]: unknown;
   }
 ): Promise<ScreenshotResult | null>;
@@ -573,6 +600,7 @@ export function vizzlyScreenshot(
 export function configure(config?: {
   serverUrl?: string;
   enabled?: boolean;
+  failOnDiff?: boolean;
 }): void;
 
 /** Enable or disable screenshot capture */

package/dist/uploader/core.js

@@ -123,6 +123,25 @@ export function extractBrowserFromFilename(filename) {
 // Build Info Construction
 // ============================================================================
 
+function buildUploadMetadata(options) {
+  let metadata = {
+    ...(options.metadata || {})
+  };
+  let comparison = {
+    ...(metadata.comparison || {})
+  };
+  if (options.threshold !== undefined) {
+    comparison.threshold = options.threshold;
+  }
+  if (options.minClusterSize !== undefined) {
+    comparison.minClusterSize = options.minClusterSize;
+  }
+  if (Object.keys(comparison).length > 0) {
+    metadata.comparison = comparison;
+  }
+  return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
+
 /**
  * Build API build info payload
  * @param {Object} options - Upload options
@@ -130,7 +149,7 @@ export function extractBrowserFromFilename(filename) {
  * @returns {Object} Build info payload
  */
 export function buildBuildInfo(options, defaultBranch = 'main') {
-  return {
+  let buildInfo = {
     name: options.buildName || `Upload ${new Date().toISOString()}`,
     branch: options.branch || defaultBranch || 'main',
     commit_sha: options.commit,
@@ -140,6 +159,11 @@ export function buildBuildInfo(options, defaultBranch = 'main') {
     github_pull_request_number: options.pullRequestNumber,
     parallel_id: options.parallelId
   };
+  let metadata = buildUploadMetadata(options);
+  if (metadata) {
+    buildInfo.metadata = metadata;
+  }
+  return buildInfo;
 }
 
 // ============================================================================
@@ -316,17 +340,25 @@ export function buildUploadResult({
  * @returns {Object} Wait result
  */
 export function buildWaitResult(build) {
+  let totalComparisons = build.comparisonsTotal ?? build.total_comparisons ?? 0;
+  let passedComparisons = build.comparisonsPassed ?? build.passed_comparisons ?? build.identicalComparisons ?? build.identical_comparisons ?? 0;
+  let failedComparisons = build.comparisonsFailed ?? build.failed_comparisons ?? build.changedComparisons ?? build.changed_comparisons ?? 0;
+  let newComparisons = build.comparisonsNew ?? build.newComparisons ?? build.new_comparisons ?? 0;
+  let identicalComparisons = build.identicalComparisons ?? build.identical_comparisons ?? passedComparisons;
+  let approvalStatus = build.approvalStatus ?? build.approval_status ?? 'pending';
+  let hasComparisonCounts = build.comparisonsTotal !== undefined || build.total_comparisons !== undefined || build.comparisonsPassed !== undefined || build.passed_comparisons !== undefined || build.comparisonsFailed !== undefined || build.failed_comparisons !== undefined || build.comparisonsNew !== undefined || build.new_comparisons !== undefined || build.identicalComparisons !== undefined || build.identical_comparisons !== undefined;
   let result = {
     status: 'completed',
-    build
+    build,
+    passedComparisons,
+    failedComparisons,
+    newComparisons,
+    identicalComparisons,
+    approvalStatus,
+    totalComparisons
   };
-  if (typeof build.comparisonsTotal === 'number') {
-    result.comparisons = build.comparisonsTotal;
-    result.passedComparisons = build.comparisonsPassed || 0;
-    result.failedComparisons = build.comparisonsFailed || 0;
-  } else {
-    result.passedComparisons = 0;
-    result.failedComparisons = 0;
+  if (hasComparisonCounts) {
+    result.comparisons = totalComparisons;
   }
   if (build.url) {
     result.url = build.url;

package/dist/uploader/operations.js

@@ -386,23 +386,25 @@ export async function upload({
     let buildInfo = buildBuildInfo(uploadOptions, defaultBranch);
     let build = await createBuild(client, buildInfo);
     let buildId = build.id;
-
-    // Check existing files
-    let {
-      toUpload,
-      existing,
-      screenshots
-    } = await checkExistingFiles({
-      fileMetadata,
-      client,
-      signal,
-      buildId,
-      deps: {
-        checkShas,
-        createError,
-        output
-      }
-    });
+    let toUpload = fileMetadata;
+    let existing = [];
+    let screenshots = [];
+    if (!uploadOptions.uploadAll) {
+      let existingResult = await checkExistingFiles({
+        fileMetadata,
+        client,
+        signal,
+        buildId,
+        deps: {
+          checkShas,
+          createError,
+          output
+        }
+      });
+      toUpload = existingResult.toUpload;
+      existing = existingResult.existing;
+      screenshots = existingResult.screenshots;
+    }
     onProgress(buildDeduplicationProgress(toUpload.length, existing.length, files.length));
 
     // Upload files

package/dist/utils/config-loader.js

@@ -2,7 +2,7 @@ import { resolve } from 'node:path';
 import { cosmiconfigSync } from 'cosmiconfig';
 import { CONFIG_DEFAULTS, deepMerge } from '../config/core.js';
 import { validateVizzlyConfigWithDefaults } from './config-schema.js';
-import { getApiToken, getApiUrl, getBuildName, getParallelId } from './environment-config.js';
+import { getApiToken, getApiUrl, getBuildName, getMinClusterSize, getParallelId, getThreshold } from './environment-config.js';
 import { getAccessToken } from './global-config.js';
 import * as output from './output.js';
 import { getActiveProjectLink } from './project-link-store.js';
@@ -26,10 +26,12 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
   mergeConfig(config, validatedFileConfig);
 
   // 3. Override with environment variables (higher priority than fallbacks)
-  const envApiKey = getApiToken();
-  const envApiUrl = getApiUrl();
-  const envBuildName = getBuildName();
-  const envParallelId = getParallelId();
+  let envApiKey = getApiToken();
+  let envApiUrl = getApiUrl();
+  let envBuildName = getBuildName();
+  let envParallelId = getParallelId();
+  let envThreshold = getThreshold();
+  let envMinClusterSize = getMinClusterSize();
   if (envApiKey) {
     config.apiKey = envApiKey;
     output.debug('config', 'using token from environment');
@@ -40,6 +42,10 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
     output.debug('config', 'using build name from environment');
   }
   if (envParallelId) config.parallelId = envParallelId;
+  if (envThreshold !== undefined) config.comparison.threshold = envThreshold;
+  if (envMinClusterSize !== undefined) {
+    config.comparison.minClusterSize = envMinClusterSize;
+  }
 
   // 4. Apply CLI overrides (highest priority)
   if (cliOverrides.token) {
@@ -109,7 +115,7 @@ function applyCLIOverrides(config, cliOverrides = {}) {
   }
 
   // Comparison overrides
-  if (cliOverrides.threshold !== undefined) config.comparison.threshold = cliOverrides.threshold;
+  if (cliOverrides.threshold !== undefined) config.comparison.threshold = Number(cliOverrides.threshold);
   if (cliOverrides.minClusterSize !== undefined) {
     config.comparison.minClusterSize = Number(cliOverrides.minClusterSize);
   }

package/dist/utils/context.js

@@ -11,6 +11,37 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+function getGlobalConfigPath() {
+  return join(process.env.VIZZLY_HOME || join(homedir(), '.vizzly'), 'config.json');
+}
+function readJsonFile(path) {
+  try {
+    if (existsSync(path)) {
+      return JSON.parse(readFileSync(path, 'utf8'));
+    }
+  } catch {
+    // Optional context should never block the command that is rendering it.
+  }
+  return null;
+}
+function readGlobalConfig() {
+  return readJsonFile(getGlobalConfigPath()) || {};
+}
+function readBaselineInfo(cwd) {
+  let path = join(cwd, '.vizzly', 'baselines');
+  let metadata = readJsonFile(join(path, 'metadata.json'));
+  return {
+    count: metadata?.screenshots?.length || 0,
+    path: metadata ? path : null
+  };
+}
+function readServerInfo(cwd) {
+  let serverInfo = readJsonFile(join(cwd, '.vizzly', 'server.json'));
+  return {
+    running: !!serverInfo,
+    port: serverInfo ? serverInfo.port : null
+  };
+}
 
 /**
  * Get dynamic context about the current Vizzly state
@@ -22,46 +53,12 @@ export function getContext() {
   let items = [];
   try {
     let cwd = process.cwd();
-    let globalConfigPath = join(process.env.VIZZLY_HOME || join(homedir(), '.vizzly'), 'config.json');
-
-    // Load global config once
-    let globalConfig = {};
-    try {
-      if (existsSync(globalConfigPath)) {
-        globalConfig = JSON.parse(readFileSync(globalConfigPath, 'utf8'));
-      }
-    } catch {
-      // Ignore
-    }
+    let globalConfig = readGlobalConfig();
 
     // Check for vizzly.config.js (project config)
     let hasProjectConfig = existsSync(join(cwd, 'vizzly.config.js'));
-
-    // Check for .vizzly directory (TDD baselines)
-    let baselineCount = 0;
-    try {
-      let metaPath = join(cwd, '.vizzly', 'baselines', 'metadata.json');
-      if (existsSync(metaPath)) {
-        let meta = JSON.parse(readFileSync(metaPath, 'utf8'));
-        baselineCount = meta.screenshots?.length || 0;
-      }
-    } catch {
-      // Ignore
-    }
-
-    // Check for TDD server running
-    let serverRunning = false;
-    let serverPort = null;
-    try {
-      let serverFile = join(cwd, '.vizzly', 'server.json');
-      if (existsSync(serverFile)) {
-        let serverInfo = JSON.parse(readFileSync(serverFile, 'utf8'));
-        serverPort = serverInfo.port;
-        serverRunning = true;
-      }
-    } catch {
-      // Ignore
-    }
+    let baselineInfo = readBaselineInfo(cwd);
+    let serverInfo = readServerInfo(cwd);
 
     // Check for OAuth login (from vizzly login)
     let isLoggedIn = !!globalConfig.auth?.accessToken;
@@ -71,11 +68,11 @@ export function getContext() {
     let hasEnvToken = !!process.env.VIZZLY_TOKEN;
 
     // Build context items - prioritize most useful info
-    if (serverRunning) {
+    if (serverInfo.running) {
       items.push({
         type: 'success',
         label: 'TDD Server',
-        value: `running on :${serverPort}`
+        value: `running on :${serverInfo.port}`
       });
     }
     if (isLoggedIn && userName) {
@@ -97,14 +94,14 @@ export function getContext() {
         value: 'run vizzly login'
       });
     }
-    if (baselineCount > 0) {
+    if (baselineInfo.count > 0) {
       items.push({
         type: 'success',
         label: 'Baselines',
-        value: `${baselineCount} screenshots`
+        value: `${baselineInfo.count} screenshots`
       });
     }
-    if (!hasProjectConfig && !serverRunning && baselineCount === 0) {
+    if (!hasProjectConfig && !serverInfo.running && baselineInfo.count === 0) {
       // Only show "no config" hint if there's nothing else useful
       items.push({
         type: 'info',
@@ -126,7 +123,6 @@ export function getContext() {
  */
 export function getDetailedContext() {
   let cwd = process.cwd();
-  let globalConfigPath = join(process.env.VIZZLY_HOME || join(homedir(), '.vizzly'), 'config.json');
   let context = {
     tddServer: {
       running: false,
@@ -146,42 +142,16 @@ export function getDetailedContext() {
     }
   };
   try {
-    // Load global config
-    let globalConfig = {};
-    try {
-      if (existsSync(globalConfigPath)) {
-        globalConfig = JSON.parse(readFileSync(globalConfigPath, 'utf8'));
-      }
-    } catch {
-      // Ignore
-    }
+    let globalConfig = readGlobalConfig();
 
     // Check for vizzly.config.js
     context.project.hasConfig = existsSync(join(cwd, 'vizzly.config.js'));
-
-    // Check for baselines
-    try {
-      let metaPath = join(cwd, '.vizzly', 'baselines', 'metadata.json');
-      if (existsSync(metaPath)) {
-        let meta = JSON.parse(readFileSync(metaPath, 'utf8'));
-        context.baselines.count = meta.screenshots?.length || 0;
-        context.baselines.path = join(cwd, '.vizzly', 'baselines');
-      }
-    } catch {
-      // Ignore
-    }
-
-    // Check for TDD server
-    try {
-      let serverFile = join(cwd, '.vizzly', 'server.json');
-      if (existsSync(serverFile)) {
-        let serverInfo = JSON.parse(readFileSync(serverFile, 'utf8'));
-        context.tddServer.running = true;
-        context.tddServer.port = serverInfo.port;
-      }
-    } catch {
-      // Ignore
-    }
+    let baselineInfo = readBaselineInfo(cwd);
+    context.baselines.count = baselineInfo.count;
+    context.baselines.path = baselineInfo.path;
+    let serverInfo = readServerInfo(cwd);
+    context.tddServer.running = serverInfo.running;
+    context.tddServer.port = serverInfo.port;
 
     // Check auth status
     context.auth.loggedIn = !!globalConfig.auth?.accessToken;

package/dist/utils/environment-config.js

@@ -85,6 +85,24 @@ export function getBuildName() {
   return process.env.VIZZLY_BUILD_NAME;
 }
 
+/**
+ * Get comparison threshold from environment
+ * @returns {number|undefined} Threshold value when set
+ */
+export function getThreshold() {
+  if (process.env.VIZZLY_THRESHOLD === undefined) return undefined;
+  return Number(process.env.VIZZLY_THRESHOLD);
+}
+
+/**
+ * Get minimum changed cluster size from environment
+ * @returns {number|undefined} Minimum cluster size when set
+ */
+export function getMinClusterSize() {
+  if (process.env.VIZZLY_MIN_CLUSTER_SIZE === undefined) return undefined;
+  return Number(process.env.VIZZLY_MIN_CLUSTER_SIZE);
+}
+
 /**
  * Check if TDD mode is enabled
  * @returns {boolean} Whether TDD mode is enabled
@@ -117,6 +135,8 @@ export function getAllEnvironmentConfig() {
     buildId: getBuildId(),
     buildName: getBuildName(),
     parallelId: getParallelId(),
+    threshold: getThreshold(),
+    minClusterSize: getMinClusterSize(),
     tddMode: isTddMode()
   };
 }

package/dist/utils/output.js

@@ -282,7 +282,7 @@ export function success(message, data = {}) {
   });
   if (config.silent) return;
   if (config.json) {
-    console.log(JSON.stringify({
+    console.error(JSON.stringify({
       status: 'success',
       message,
       ...data
@@ -301,7 +301,7 @@ export function result(message) {
   if (config.silent) return;
   const elapsed = getElapsedTime();
   if (config.json) {
-    console.log(JSON.stringify({
+    console.error(JSON.stringify({
       status: 'complete',
       message,
       elapsed
@@ -319,7 +319,7 @@ export function info(message, data = {}) {
   writeLog('info', message, data);
   if (!shouldLog('info')) return;
   if (config.json) {
-    console.log(JSON.stringify({
+    console.error(JSON.stringify({
       status: 'info',
       message,
       ...data
@@ -513,7 +513,7 @@ export function stopSpinner() {
 export function progress(message, current = 0, total = 0) {
   if (config.silent) return;
   if (config.json) {
-    console.log(JSON.stringify({
+    console.error(JSON.stringify({
       status: 'progress',
       message,
       progress: {
@@ -941,7 +941,7 @@ export function complete(message, options = {}) {
   } = options;
   let detailStr = detail ? ` ${colors.brand.textMuted(detail)}` : '';
   if (config.json) {
-    console.log(JSON.stringify({
+    console.error(JSON.stringify({
       status: 'complete',
       message,
       detail

package/dist/utils/screenshot-options.js

@@ -1,21 +1,63 @@
+/**
+ * Screenshot option names that are part of the SDK/config contract, not the
+ * user's arbitrary metadata bag.
+ */
+export let RESERVED_PROPERTY_OPTIONS = Object.freeze({
+  threshold: {
+    message: 'Move "threshold" out of properties; properties is only for user metadata.'
+  },
+  minClusterSize: {
+    message: 'Move "minClusterSize" out of properties; properties is only for user metadata.'
+  },
+  fullPage: {
+    message: 'Move "fullPage" out of properties; properties is only for user metadata.'
+  },
+  buildId: {
+    message: 'Move "buildId" out of properties; properties is only for user metadata.'
+  },
+  requestTimeout: {
+    message: 'Move "requestTimeout" out of properties; properties is only for user metadata.'
+  }
+});
+function createReservedPropertyWarning(option) {
+  return {
+    code: 'reserved-property-option',
+    option,
+    message: RESERVED_PROPERTY_OPTIONS[option].message
+  };
+}
+
 /**
  * Normalize screenshot SDK options into the properties payload consumed by the
  * local TDD server and cloud-compatible comparison path.
  */
-export function createScreenshotProperties(options = {}) {
+export function normalizeScreenshotOptions(options = {}) {
   let {
-    buildId: _buildId,
+    buildId,
     properties = {},
-    requestTimeout: _requestTimeout,
+    requestTimeout,
     threshold,
     minClusterSize,
-    fullPage,
-    ...topLevelProperties
+    fullPage
   } = options;
-  let normalizedProperties = {
-    ...topLevelProperties,
-    ...properties
-  };
+  let warnings = [];
+  let normalizedProperties = {};
+  for (let [key, value] of Object.entries(properties || {})) {
+    if (RESERVED_PROPERTY_OPTIONS[key]) {
+      warnings.push(createReservedPropertyWarning(key));
+      if (key === 'threshold' && threshold === undefined) threshold = value;
+      if (key === 'minClusterSize' && minClusterSize === undefined) {
+        minClusterSize = value;
+      }
+      if (key === 'fullPage' && fullPage === undefined) fullPage = value;
+      if (key === 'buildId' && buildId === undefined) buildId = value;
+      if (key === 'requestTimeout' && requestTimeout === undefined) {
+        requestTimeout = value;
+      }
+      continue;
+    }
+    normalizedProperties[key] = value;
+  }
   if (threshold !== undefined) {
     normalizedProperties.threshold = threshold;
   }
@@ -25,5 +67,13 @@ export function createScreenshotProperties(options = {}) {
   if (fullPage !== undefined) {
     normalizedProperties.fullPage = fullPage;
   }
-  return normalizedProperties;
+  return {
+    buildId,
+    requestTimeout,
+    properties: normalizedProperties,
+    warnings
+  };
+}
+export function createScreenshotProperties(options = {}) {
+  return normalizeScreenshotOptions(options).properties;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",