@vizzly-testing/cli 0.30.0 → 0.32.0

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

@@ -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;
 }
 
 /**

package/dist/uploader/index.js

@@ -1,11 +1,88 @@
 /**
  * Uploader Module
  *
- * Exports pure functions (core) and I/O operations for screenshot uploading.
+ * Exports pure functions (core), I/O operations, and the public uploader
+ * factory for screenshot uploading.
  */
 
+import { readFile, stat } from 'node:fs/promises';
+import { glob } from 'glob';
+import { checkShas, createApiClient, createBuild } from '../api/index.js';
+import { TimeoutError, UploadError, ValidationError } from '../errors/vizzly-error.js';
+import { getDefaultBranch } from '../utils/git.js';
+import * as output from '../utils/output.js';
+import { resolveBatchSize, resolveTimeout } from './core.js';
+import { upload as uploadOperation, waitForBuild as waitForBuildOperation } from './operations.js';
+export function createUploader({
+  apiKey,
+  apiUrl,
+  userAgent,
+  command,
+  upload: uploadConfig = {}
+} = {}, options = {}) {
+  let signal = options.signal || new AbortController().signal;
+  let client = createApiClient({
+    baseUrl: apiUrl,
+    token: apiKey,
+    command: command || 'upload',
+    sdkUserAgent: userAgent,
+    allowNoToken: true
+  });
+  let batchSize = resolveBatchSize(options, uploadConfig);
+  let timeout = resolveTimeout(options, uploadConfig);
+  let deps = options.deps || {
+    client,
+    createBuild,
+    getDefaultBranch,
+    glob,
+    readFile,
+    stat,
+    checkShas,
+    createError: (message, code, context) => {
+      let error = new UploadError(message, context);
+      error.code = code;
+      return error;
+    },
+    createValidationError: (message, context) => new ValidationError(message, context),
+    createUploadError: (message, context) => new UploadError(message, context),
+    createTimeoutError: (message, context) => new TimeoutError(message, context),
+    output
+  };
+  async function upload(uploadOptions) {
+    return uploadOperation({
+      uploadOptions,
+      config: {
+        apiKey,
+        apiUrl
+      },
+      signal,
+      batchSize,
+      deps: {
+        ...deps,
+        client: deps.client || client
+      }
+    });
+  }
+  async function waitForBuild(buildId, waitTimeout = timeout) {
+    return waitForBuildOperation({
+      buildId,
+      timeout: waitTimeout,
+      signal,
+      client: deps.client || client,
+      deps: {
+        createError: deps.createError,
+        createTimeoutError: deps.createTimeoutError
+      }
+    });
+  }
+  return {
+    upload,
+    waitForBuild
+  };
+}
+
 // Core - pure functions
-export { buildBuildInfo, buildCompletedProgress, buildDeduplicationProgress, buildFileMetadata, buildProcessingProgress, buildScanningProgress, buildScreenshotPattern, buildUploadingProgress, buildUploadResult, buildWaitResult, computeSha256, DEFAULT_BATCH_SIZE, DEFAULT_SHA_CHECK_BATCH_SIZE, DEFAULT_TIMEOUT, extractBrowserFromFilename, extractStatusCodeFromError, fileToScreenshotFormat, getElapsedTime, isTimedOut, partitionFilesByExistence, resolveBatchSize, resolveTimeout, validateApiKey, validateDirectoryStats, validateFilesFound, validateScreenshotsDir } from './core.js';
+export { buildBuildInfo, buildCompletedProgress, buildDeduplicationProgress, buildFileMetadata, buildProcessingProgress, buildScanningProgress, buildScreenshotPattern, buildUploadingProgress, buildUploadResult, buildWaitResult, computeSha256, DEFAULT_BATCH_SIZE, DEFAULT_BUILD_POLL_INTERVAL, DEFAULT_SHA_CHECK_BATCH_SIZE, DEFAULT_TIMEOUT, extractBrowserFromFilename, extractStatusCodeFromError, fileToScreenshotFormat, getElapsedTime, isTimedOut, partitionFilesByExistence, resolveBatchSize, resolveTimeout, validateApiKey, validateDirectoryStats, validateFilesFound, validateScreenshotsDir } from './core.js';
 
 // Operations - I/O with dependency injection
 export { checkExistingFiles, findScreenshots, processFiles, upload, uploadFiles, waitForBuild } from './operations.js';

package/dist/uploader/operations.js

@@ -4,7 +4,34 @@
  * Each operation takes its dependencies as parameters for testability.
  */
 
-import { buildBuildInfo, buildCompletedProgress, buildDeduplicationProgress, buildFileMetadata, buildProcessingProgress, buildScanningProgress, buildScreenshotPattern, buildUploadingProgress, buildUploadResult, buildWaitResult, DEFAULT_SHA_CHECK_BATCH_SIZE, extractStatusCodeFromError, fileToScreenshotFormat, getElapsedTime, isTimedOut, partitionFilesByExistence, validateApiKey, validateDirectoryStats, validateFilesFound, validateScreenshotsDir } from './core.js';
+import { buildBuildInfo, buildCompletedProgress, buildDeduplicationProgress, buildFileMetadata, buildProcessingProgress, buildScanningProgress, buildScreenshotPattern, buildUploadingProgress, buildUploadResult, buildWaitResult, DEFAULT_BUILD_POLL_INTERVAL, DEFAULT_SHA_CHECK_BATCH_SIZE, extractStatusCodeFromError, fileToScreenshotFormat, getElapsedTime, isTimedOut, partitionFilesByExistence, validateApiKey, validateDirectoryStats, validateFilesFound, validateScreenshotsDir } from './core.js';
+function delay(ms, signal) {
+  if (ms <= 0) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    let timeoutId;
+    function cleanup() {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener?.('abort', handleAbort);
+    }
+    function handleAbort() {
+      cleanup();
+      reject(new Error('Operation cancelled'));
+    }
+    timeoutId = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    if (signal?.aborted) {
+      handleAbort();
+      return;
+    }
+    signal?.addEventListener?.('abort', handleAbort, {
+      once: true
+    });
+  });
+}
 
 // ============================================================================
 // File Discovery
@@ -228,10 +255,13 @@ export async function waitForBuild({
 }) {
   let {
     createError,
-    createTimeoutError
+    createTimeoutError,
+    now = () => Date.now(),
+    pollInterval = DEFAULT_BUILD_POLL_INTERVAL,
+    wait = delay
   } = deps;
-  let startTime = Date.now();
-  while (!isTimedOut(startTime, timeout)) {
+  let startTime = now();
+  while (!isTimedOut(startTime, timeout, now())) {
     if (signal.aborted) {
       throw createError('Operation cancelled', 'UPLOAD_CANCELLED', {
         buildId
@@ -253,11 +283,16 @@ export async function waitForBuild({
     if (build.status === 'failed') {
       throw createError(`Build failed: ${build.error || 'Unknown error'}`, 'BUILD_FAILED');
     }
+    let remaining = timeout - getElapsedTime(startTime, now());
+    if (remaining <= 0) {
+      break;
+    }
+    await wait(Math.min(pollInterval, remaining), signal);
   }
   throw createTimeoutError(`Build timed out after ${timeout}ms`, {
     buildId,
     timeout,
-    elapsed: getElapsedTime(startTime)
+    elapsed: getElapsedTime(startTime, now())
   });
 }
 

package/dist/utils/api-url.js

@@ -0,0 +1,14 @@
+export function getAppBaseUrl(apiUrl) {
+  try {
+    let url = new URL(apiUrl);
+    let apiPathIndex = url.pathname.indexOf('/api');
+    if (apiPathIndex !== -1) {
+      url.pathname = url.pathname.slice(0, apiPathIndex) || '/';
+      url.search = '';
+      url.hash = '';
+    }
+    return url.toString().replace(/\/$/, '');
+  } catch {
+    return apiUrl.replace(/\/api(?:\/.*)?$/, '');
+  }
+}

package/dist/utils/async-utils.js

@@ -0,0 +1,26 @@
+/**
+ * Race an operation against a timeout and always clear the timer when either
+ * side settles.
+ *
+ * @param {Promise<unknown>} operation - Operation promise to wait for.
+ * @param {number} ms - Timeout in milliseconds.
+ * @param {string} message - Error message when the timeout wins.
+ * @param {Object} [timers] - Timer implementation for deterministic tests.
+ * @returns {Promise<unknown>} The operation result.
+ */
+export async function withTimeout(operation, ms, message, timers = {
+  setTimeout,
+  clearTimeout
+}) {
+  let timeoutId;
+  let timeoutPromise = new Promise((_, reject) => {
+    timeoutId = timers.setTimeout(() => reject(new Error(message)), ms);
+  });
+  try {
+    return await Promise.race([operation, timeoutPromise]);
+  } finally {
+    if (timeoutId !== undefined) {
+      timers.clearTimeout(timeoutId);
+    }
+  }
+}

package/dist/utils/ci-env.js

@@ -176,6 +176,13 @@ export function getCommitMessage() {
   // Generic
   null;
 }
+function parsePullRequestNumber(value) {
+  if (!/^\d+$/.test(value)) {
+    return null;
+  }
+  let number = Number(value);
+  return Number.isSafeInteger(number) && number > 0 ? number : null;
+}
 
 /**
  * Get the pull request number from CI environment variables
@@ -184,54 +191,54 @@ export function getCommitMessage() {
 export function getPullRequestNumber() {
   // Check VIZZLY override first
   if (process.env.VIZZLY_PR_NUMBER) {
-    return parseInt(process.env.VIZZLY_PR_NUMBER, 10);
+    return parsePullRequestNumber(process.env.VIZZLY_PR_NUMBER);
   }
 
   // GitHub Actions - extract from GITHUB_REF
   if (process.env.GITHUB_ACTIONS && process.env.GITHUB_EVENT_NAME === 'pull_request') {
-    const prMatch = process.env.GITHUB_REF?.match(/refs\/pull\/(\d+)\/merge/);
-    if (prMatch?.[1]) return parseInt(prMatch[1], 10);
+    let prMatch = process.env.GITHUB_REF?.match(/refs\/pull\/(\d+)\/merge/);
+    if (prMatch?.[1]) return parsePullRequestNumber(prMatch[1]);
   }
 
   // GitLab CI
   if (process.env.CI_MERGE_REQUEST_ID) {
-    return parseInt(process.env.CI_MERGE_REQUEST_ID, 10);
+    return parsePullRequestNumber(process.env.CI_MERGE_REQUEST_ID);
   }
 
   // CircleCI - extract from PR URL
   if (process.env.CIRCLE_PULL_REQUEST) {
-    const prMatch = process.env.CIRCLE_PULL_REQUEST.match(/\/pull\/(\d+)$/);
-    if (prMatch?.[1]) return parseInt(prMatch[1], 10);
+    let prMatch = process.env.CIRCLE_PULL_REQUEST.match(/\/pull\/(\d+)$/);
+    if (prMatch?.[1]) return parsePullRequestNumber(prMatch[1]);
   }
 
   // Travis CI
   if (process.env.TRAVIS_PULL_REQUEST && process.env.TRAVIS_PULL_REQUEST !== 'false') {
-    return parseInt(process.env.TRAVIS_PULL_REQUEST, 10);
+    return parsePullRequestNumber(process.env.TRAVIS_PULL_REQUEST);
   }
 
   // Buildkite
   if (process.env.BUILDKITE_PULL_REQUEST && process.env.BUILDKITE_PULL_REQUEST !== 'false') {
-    return parseInt(process.env.BUILDKITE_PULL_REQUEST, 10);
+    return parsePullRequestNumber(process.env.BUILDKITE_PULL_REQUEST);
   }
 
   // Drone CI
   if (process.env.DRONE_PULL_REQUEST) {
-    return parseInt(process.env.DRONE_PULL_REQUEST, 10);
+    return parsePullRequestNumber(process.env.DRONE_PULL_REQUEST);
   }
 
   // Jenkins (GitHub Pull Request Builder plugin)
   if (process.env.ghprbPullId) {
-    return parseInt(process.env.ghprbPullId, 10);
+    return parsePullRequestNumber(process.env.ghprbPullId);
   }
 
   // Azure DevOps
   if (process.env.SYSTEM_PULLREQUEST_PULLREQUESTID) {
-    return parseInt(process.env.SYSTEM_PULLREQUEST_PULLREQUESTID, 10);
+    return parsePullRequestNumber(process.env.SYSTEM_PULLREQUEST_PULLREQUESTID);
   }
 
   // AppVeyor
   if (process.env.APPVEYOR_PULL_REQUEST_NUMBER) {
-    return parseInt(process.env.APPVEYOR_PULL_REQUEST_NUMBER, 10);
+    return parsePullRequestNumber(process.env.APPVEYOR_PULL_REQUEST_NUMBER);
   }
   return null;
 }