@vizzly-testing/cli 0.29.6 → 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/colors.js

@@ -1,7 +1,7 @@
 // Color utility using ansis for rich terminal styling.
 // Detects terminal color support and provides chainable color functions.
 
-import ansis from 'ansis';
+import { Ansis } from 'ansis';
 
 // =============================================================================
 // Vizzly Observatory Design System Colors
@@ -72,7 +72,7 @@ function supportsColorDefault() {
   }
 
   // If stdout is not a TTY, assume no color
-  if (!process.stdout || !process.stdout.isTTY) return false;
+  if (!process.stdout?.isTTY) return false;
 
   // Prefer getColorDepth when available
   try {
@@ -92,6 +92,7 @@ function supportsColorDefault() {
  */
 export function createColors(options = {}) {
   let enabled = options.useColor !== undefined ? !!options.useColor : supportsColorDefault();
+  let level = options.useColor !== undefined ? enabled ? 3 : 0 : enabled ? 3 : 0;
   if (!enabled) {
     // Return no-op functions when color disabled
     let noop = (input = '') => String(input);
@@ -152,60 +153,61 @@ export function createColors(options = {}) {
       }
     };
   }
+  let colors = new Ansis(level);
   return {
     // Modifiers
-    reset: ansis.reset,
-    bold: ansis.bold,
-    dim: ansis.dim,
-    italic: ansis.italic,
-    underline: ansis.underline,
-    strikethrough: ansis.strikethrough,
+    reset: colors.reset,
+    bold: colors.bold,
+    dim: colors.dim,
+    italic: colors.italic,
+    underline: colors.underline,
+    strikethrough: colors.strikethrough,
     // Basic ANSI colors (fallback)
-    red: ansis.red,
-    green: ansis.green,
-    yellow: ansis.yellow,
-    blue: ansis.blue,
-    magenta: ansis.magenta,
-    cyan: ansis.cyan,
-    white: ansis.white,
-    gray: ansis.gray,
-    black: ansis.black,
+    red: colors.red,
+    green: colors.green,
+    yellow: colors.yellow,
+    blue: colors.blue,
+    magenta: colors.magenta,
+    cyan: colors.cyan,
+    white: colors.white,
+    gray: colors.gray,
+    black: colors.black,
     // Semantic aliases (basic)
-    success: ansis.green,
-    error: ansis.red,
-    warning: ansis.yellow,
-    info: ansis.blue,
+    success: colors.green,
+    error: colors.red,
+    warning: colors.yellow,
+    info: colors.blue,
     // Extended colors for rich styling
-    rgb: ansis.rgb,
-    hex: ansis.hex,
-    bgRgb: ansis.bgRgb,
-    bgHex: ansis.bgHex,
+    rgb: colors.rgb.bind(colors),
+    hex: colors.hex.bind(colors),
+    bgRgb: colors.bgRgb.bind(colors),
+    bgHex: colors.bgHex.bind(colors),
     // Observatory brand colors (Truecolor) - aligned with design system
     brand: {
       // Primary brand color
-      amber: ansis.hex(brand.amber),
-      amberLight: ansis.hex(brand.amberLight),
+      amber: colors.hex(brand.amber),
+      amberLight: colors.hex(brand.amberLight),
       // Semantic accents
-      success: ansis.hex(brand.success),
-      warning: ansis.hex(brand.warning),
-      danger: ansis.hex(brand.danger),
-      info: ansis.hex(brand.info),
+      success: colors.hex(brand.success),
+      warning: colors.hex(brand.warning),
+      danger: colors.hex(brand.danger),
+      info: colors.hex(brand.info),
       // Text hierarchy
-      textPrimary: ansis.hex(brand.textPrimary),
-      textSecondary: ansis.hex(brand.textSecondary),
-      textTertiary: ansis.hex(brand.textTertiary),
-      textMuted: ansis.hex(brand.textMuted),
+      textPrimary: colors.hex(brand.textPrimary),
+      textSecondary: colors.hex(brand.textSecondary),
+      textTertiary: colors.hex(brand.textTertiary),
+      textMuted: colors.hex(brand.textMuted),
       // Background variants
-      bgAmber: ansis.bgHex(brand.amber),
-      bgSuccess: ansis.bgHex(brand.success),
-      bgWarning: ansis.bgHex(brand.warning),
-      bgDanger: ansis.bgHex(brand.danger),
-      bgInfo: ansis.bgHex(brand.info),
+      bgAmber: colors.bgHex(brand.amber),
+      bgSuccess: colors.bgHex(brand.success),
+      bgWarning: colors.bgHex(brand.warning),
+      bgDanger: colors.bgHex(brand.danger),
+      bgInfo: colors.bgHex(brand.info),
       // Legacy aliases (backward compatibility)
-      green: ansis.hex(brand.green),
-      red: ansis.hex(brand.red),
-      cyan: ansis.hex(brand.cyan),
-      slate: ansis.hex(brand.slate)
+      green: colors.hex(brand.green),
+      red: colors.hex(brand.red),
+      cyan: colors.hex(brand.cyan),
+      slate: colors.hex(brand.slate)
     }
   };
 }

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;