@vizzly-testing/cli 0.30.0 → 0.31.0

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;
 }

package/dist/utils/config-loader.js

@@ -1,45 +1,15 @@
 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 { getAccessToken } from './global-config.js';
 import * as output from './output.js';
-const DEFAULT_CONFIG = {
-  // API Configuration
-  apiKey: undefined,
-  // Will be set from env, global config, or CLI overrides
-  apiUrl: getApiUrl(),
-  // Server Configuration (for run command)
-  server: {
-    port: 47392,
-    timeout: 30000
-  },
-  // Build Configuration
-  build: {
-    name: 'Build {timestamp}',
-    environment: 'test'
-  },
-  // Upload Configuration (for upload command)
-  upload: {
-    screenshotsDir: './screenshots',
-    batchSize: 10,
-    timeout: 30000
-  },
-  // Comparison Configuration (CIEDE2000 Delta E: 0=exact, 1=JND, 2=recommended)
-  comparison: {
-    threshold: 2.0
-  },
-  // TDD Configuration
-  tdd: {
-    openReport: false // Whether to auto-open HTML report in browser
-  },
-  // Plugins
-  plugins: []
-};
+import { getActiveProjectLink } from './project-link-store.js';
 export async function loadConfig(configPath = null, cliOverrides = {}) {
   // 1. Load from config file using cosmiconfig
-  const explorer = cosmiconfigSync('vizzly');
-  const result = configPath ? explorer.load(configPath) : explorer.search();
+  let explorer = cosmiconfigSync('vizzly');
+  let result = configPath ? explorer.load(configPath) : explorer.search();
   let fileConfig = {};
   if (result?.config) {
     // Handle ESM default export (cosmiconfig wraps it in { default: {...} })
@@ -47,28 +17,10 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
   }
 
   // 2. Validate config file using Zod schema
-  const validatedFileConfig = validateVizzlyConfigWithDefaults(fileConfig);
+  let validatedFileConfig = validateVizzlyConfigWithDefaults(fileConfig);
 
   // Create a proper clone of the default config to avoid shared object references
-  const config = {
-    ...DEFAULT_CONFIG,
-    server: {
-      ...DEFAULT_CONFIG.server
-    },
-    build: {
-      ...DEFAULT_CONFIG.build
-    },
-    upload: {
-      ...DEFAULT_CONFIG.upload
-    },
-    comparison: {
-      ...DEFAULT_CONFIG.comparison
-    },
-    tdd: {
-      ...DEFAULT_CONFIG.tdd
-    },
-    plugins: [...DEFAULT_CONFIG.plugins]
-  };
+  let config = deepMerge(CONFIG_DEFAULTS, {});
 
   // Merge validated file config
   mergeConfig(config, validatedFileConfig);
@@ -95,16 +47,35 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
   }
   applyCLIOverrides(config, cliOverrides);
 
-  // 5. Fall back to user auth token if no other token found
-  // This enables interactive commands (builds, comparisons, approve, etc.)
-  // to work without a project token when the user is logged in
+  // 5. Fall back to a linked project token for cloud upload commands.
   if (!config.apiKey) {
-    let userToken = await getAccessToken();
-    if (userToken) {
-      config.apiKey = userToken;
-      output.debug('config', 'using token from user login');
+    let linkedProject = await getActiveProjectLink({
+      apiUrl: config.apiUrl
+    });
+    if (linkedProject?.token) {
+      config.apiKey = linkedProject.token;
+      config.linkedProject = {
+        account: linkedProject.account,
+        apiUrl: linkedProject.apiUrl,
+        organizationSlug: linkedProject.organizationSlug,
+        organizationName: linkedProject.organizationName,
+        projectSlug: linkedProject.projectSlug,
+        projectName: linkedProject.projectName,
+        tokenId: linkedProject.tokenId,
+        tokenPrefix: linkedProject.tokenPrefix,
+        expiresAt: linkedProject.expiresAt,
+        storage: linkedProject.storage
+      };
+      output.debug('config', 'using linked project token');
     }
   }
+
+  // 6. Keep user auth separate from upload credentials.
+  let userToken = await getAccessToken();
+  if (userToken) {
+    config.userToken = userToken;
+    output.debug('config', 'using user login for user-authenticated commands');
+  }
   return config;
 }
 
@@ -126,19 +97,22 @@ function applyCLIOverrides(config, cliOverrides = {}) {
   if (cliOverrides.parallelId) config.parallelId = cliOverrides.parallelId;
 
   // Server overrides
-  if (cliOverrides.port) config.server.port = parseInt(cliOverrides.port, 10);
-  if (cliOverrides.timeout) config.server.timeout = parseInt(cliOverrides.timeout, 10);
+  if (cliOverrides.port) config.server.port = Number(cliOverrides.port);
+  if (cliOverrides.timeout) config.server.timeout = Number(cliOverrides.timeout);
 
   // Upload overrides
   if (cliOverrides.batchSize !== undefined) {
-    config.upload.batchSize = parseInt(cliOverrides.batchSize, 10);
+    config.upload.batchSize = Number(cliOverrides.batchSize);
   }
   if (cliOverrides.uploadTimeout !== undefined) {
-    config.upload.timeout = parseInt(cliOverrides.uploadTimeout, 10);
+    config.upload.timeout = Number(cliOverrides.uploadTimeout);
   }
 
   // Comparison overrides
   if (cliOverrides.threshold !== undefined) config.comparison.threshold = cliOverrides.threshold;
+  if (cliOverrides.minClusterSize !== undefined) {
+    config.comparison.minClusterSize = Number(cliOverrides.minClusterSize);
+  }
 
   // Baseline overrides
   if (cliOverrides.baselineBuild) config.baselineBuildId = cliOverrides.baselineBuild;

package/dist/utils/config-schema.js

@@ -4,21 +4,22 @@
  */
 
 import { z } from 'zod';
+import { CONFIG_DEFAULTS } from '../config/core.js';
 
 /**
  * Server configuration schema
  */
 const serverSchema = z.object({
-  port: z.number().int().positive().default(47392),
-  timeout: z.number().int().positive().default(30000)
+  port: z.number().int().positive().default(CONFIG_DEFAULTS.server.port),
+  timeout: z.number().int().positive().default(CONFIG_DEFAULTS.server.timeout)
 });
 
 /**
  * Build configuration schema
  */
 const buildSchema = z.object({
-  name: z.string().default('Build {timestamp}'),
-  environment: z.string().default('test'),
+  name: z.string().default(CONFIG_DEFAULTS.build.name),
+  environment: z.string().default(CONFIG_DEFAULTS.build.environment),
   branch: z.string().optional(),
   commit: z.string().optional(),
   message: z.string().optional()
@@ -28,9 +29,9 @@ const buildSchema = z.object({
  * Upload configuration schema
  */
 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)
+  screenshotsDir: z.union([z.string(), z.array(z.string())]).default(CONFIG_DEFAULTS.upload.screenshotsDir),
+  batchSize: z.number().int().positive().default(CONFIG_DEFAULTS.upload.batchSize),
+  timeout: z.number().int().positive().default(CONFIG_DEFAULTS.upload.timeout)
 });
 
 /**
@@ -39,15 +40,15 @@ const uploadSchema = z.object({
  * minClusterSize: pixels (1 = exact)
  */
 const comparisonSchema = z.object({
-  threshold: z.number().min(0).default(2.0),
-  minClusterSize: z.int().min(1).default(2)
+  threshold: z.number().min(0).default(CONFIG_DEFAULTS.comparison.threshold),
+  minClusterSize: z.int().min(1).default(CONFIG_DEFAULTS.comparison.minClusterSize)
 });
 
 /**
  * TDD configuration schema
  */
 const tddSchema = z.object({
-  openReport: z.boolean().default(false)
+  openReport: z.boolean().default(CONFIG_DEFAULTS.tdd.openReport)
 });
 
 /**
@@ -57,29 +58,14 @@ const tddSchema = z.object({
 export const vizzlyConfigSchema = z.object({
   // Core Vizzly config
   apiKey: z.string().optional(),
-  apiUrl: z.string().url().optional(),
-  server: serverSchema.default({
-    port: 47392,
-    timeout: 30000
-  }),
-  build: buildSchema.default({
-    name: 'Build {timestamp}',
-    environment: 'test'
-  }),
-  upload: uploadSchema.default({
-    screenshotsDir: './screenshots',
-    batchSize: 10,
-    timeout: 30000
-  }),
-  comparison: comparisonSchema.default({
-    threshold: 2.0,
-    minClusterSize: 2
-  }),
-  tdd: tddSchema.default({
-    openReport: false
-  }),
+  apiUrl: z.string().url().default(CONFIG_DEFAULTS.apiUrl),
+  server: serverSchema.default(CONFIG_DEFAULTS.server),
+  build: buildSchema.default(CONFIG_DEFAULTS.build),
+  upload: uploadSchema.default(CONFIG_DEFAULTS.upload),
+  comparison: comparisonSchema.default(CONFIG_DEFAULTS.comparison),
+  tdd: tddSchema.default(CONFIG_DEFAULTS.tdd),
   signatureProperties: z.array(z.string()).default([]),
-  plugins: z.array(z.string()).default([]),
+  plugins: z.array(z.string()).default(CONFIG_DEFAULTS.plugins),
   // Additional optional fields
   parallelId: z.string().optional(),
   baselineBuildId: z.string().optional(),
@@ -88,29 +74,7 @@ export const vizzlyConfigSchema = z.object({
   wait: z.boolean().optional(),
   allowNoToken: z.boolean().optional()
 }).passthrough() // Allow plugin-specific keys like `staticSite`, `storybook`, etc.
-.default({
-  server: {
-    port: 47392,
-    timeout: 30000
-  },
-  build: {
-    name: 'Build {timestamp}',
-    environment: 'test'
-  },
-  upload: {
-    screenshotsDir: './screenshots',
-    batchSize: 10,
-    timeout: 30000
-  },
-  comparison: {
-    threshold: 2.0,
-    minClusterSize: 2
-  },
-  tdd: {
-    openReport: false
-  },
-  plugins: []
-});
+.default(CONFIG_DEFAULTS);
 
 /**
  * Validate Vizzly configuration

package/dist/utils/fetch-utils.js

@@ -1,9 +1,16 @@
-function fetchWithTimeout(url, opts = {}, ms = 300000) {
-  const ctrl = new AbortController();
-  const id = setTimeout(() => ctrl.abort(), ms);
-  return fetch(url, {
+let defaultTimers = {
+  setTimeout,
+  clearTimeout
+};
+function fetchWithTimeout(url, opts = {}, ms = 300000, deps = {}) {
+  let fetchFn = deps.fetch || fetch;
+  let AbortControllerClass = deps.AbortController || AbortController;
+  let timers = deps.timers || defaultTimers;
+  let ctrl = new AbortControllerClass();
+  let timeoutId = timers.setTimeout(() => ctrl.abort(), ms);
+  return fetchFn(url, {
     ...opts,
     signal: ctrl.signal
-  }).finally(() => clearTimeout(id));
+  }).finally(() => timers.clearTimeout(timeoutId));
 }
 export { fetchWithTimeout };