@vizzly-testing/cli 0.39.1 → 0.39.2

package/dist/domains/builds/build.validations.js

@@ -0,0 +1,39 @@
+/**
+ * Validate builds command options
+ */
+export function validateBuildsOptions(options = {}) {
+  let errors = [];
+  if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 250)) {
+    errors.push('--limit must be an integer between 1 and 250');
+  }
+  if (options.offset !== undefined && (!Number.isInteger(options.offset) || options.offset < 0)) {
+    errors.push('--offset must be a non-negative integer');
+  }
+  return errors;
+}
+
+/**
+ * Validate status options
+ * @param {string} buildId - Build ID to check
+ * @param {Object} options - Command options
+ */
+export function validateStatusOptions(buildId) {
+  let errors = [];
+  if (!buildId || buildId.trim() === '') {
+    errors.push('Build ID is required');
+  }
+  return errors;
+}
+
+/**
+ * Validate finalize options
+ * @param {string} parallelId - Parallel ID to finalize
+ * @param {Object} options - Command options
+ */
+export function validateFinalizeOptions(parallelId, _options) {
+  let errors = [];
+  if (!parallelId || parallelId.trim() === '') {
+    errors.push('Parallel ID is required');
+  }
+  return errors;
+}

package/dist/{commands/builds.js → domains/builds/builds.commands.js}

@@ -1,10 +1,13 @@
+import { formatBuildForJson } from './build.serializers.js';
+
 /**
  * Builds command - list and query builds
  */
 
-import { createApiClient as defaultCreateApiClient, getBuild as defaultGetBuild, getBuilds as defaultGetBuilds } from '../api/index.js';
-import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
-import * as defaultOutput from '../utils/output.js';
+import * as defaultOutput from '../../shared/output.js';
+import { createApiClient as defaultCreateApiClient } from '../auth/cloud-client.js';
+import { loadConfig as defaultLoadConfig } from '../config/config-loader.js';
+import { getBuild as defaultGetBuild, getBuilds as defaultGetBuilds } from './build.service.js';
 
 /**
  * Builds list command - list builds with optional filters
@@ -153,63 +156,6 @@ export async function buildsCommand(options = {}, globalOptions = {}, deps = {})
   }
 }
 
-/**
- * Format a build for JSON output
- */
-function formatBuildForJson(build, includeComparisons = false) {
-  let result = {
-    id: build.id,
-    name: build.name,
-    status: build.status,
-    branch: build.branch,
-    commit: build.commit_sha,
-    commitMessage: build.commit_message,
-    environment: build.environment,
-    screenshotCount: build.screenshot_count || 0,
-    comparisons: {
-      total: build.total_comparisons || 0,
-      new: build.new_comparisons || 0,
-      changed: build.changed_comparisons || 0,
-      identical: build.identical_comparisons || 0
-    },
-    visual_review: build.visual_review || null,
-    createdAt: build.created_at,
-    completedAt: build.completed_at
-  };
-  if (includeComparisons && build.comparisons) {
-    result.comparisonDetails = build.comparisons.map(c => {
-      let diffUrl = c.diff_image?.url || c.diff_image_url || c.diff_url || null;
-      let diffImage = c.diff_image || {};
-      let clusterMetadata = c.cluster_metadata || diffImage.cluster_metadata || null;
-      let ssimScore = c.ssim_score ?? diffImage.ssim_score ?? null;
-      let gmsdScore = c.gmsd_score ?? diffImage.gmsd_score ?? null;
-      let fingerprintHash = c.fingerprint_hash || diffImage.fingerprint_hash || null;
-      let hasHoneydiff = clusterMetadata || ssimScore != null || gmsdScore != null || fingerprintHash;
-      return {
-        id: c.id,
-        name: c.name || c.current_name,
-        status: c.status,
-        diffPercentage: c.diff_percentage,
-        visual_review: c.visual_review || null,
-        urls: {
-          baseline: c.baseline_screenshot?.original_url || c.baseline_original_url || c.baseline_screenshot_url || null,
-          current: c.current_screenshot?.original_url || c.current_original_url || c.current_screenshot_url || null,
-          diff: diffUrl
-        },
-        honeydiff: hasHoneydiff ? {
-          ssimScore,
-          gmsdScore,
-          clusterClassification: clusterMetadata?.classification || null,
-          clusterMetadata,
-          fingerprintHash,
-          diffRegions: c.diff_regions ?? diffImage.diff_regions ?? null
-        } : null
-      };
-    });
-  }
-  return result;
-}
-
 /**
  * Display a single build in human-readable format
  */
@@ -319,18 +265,4 @@ function getComparisonStatusIcon(colors, status) {
     default:
       return colors.dim('○');
   }
-}
-
-/**
- * Validate builds command options
- */
-export function validateBuildsOptions(options = {}) {
-  let errors = [];
-  if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 250)) {
-    errors.push('--limit must be an integer between 1 and 250');
-  }
-  if (options.offset !== undefined && (!Number.isInteger(options.offset) || options.offset < 0)) {
-    errors.push('--offset must be a non-negative integer');
-  }
-  return errors;
 }

package/dist/domains/builds/cloud-builds.routes.js

@@ -0,0 +1,31 @@
+import { sendError, sendSuccess } from '../../adapters/http/middleware/response.js';
+import * as output from '../../shared/output.js';
+export function createCloudBuildsRouter({
+  authService
+}) {
+  return async function handleCloudBuildsRoute(req, res, pathname, parsedUrl) {
+    let buildsMatch = pathname.match(/^\/api\/cloud\/organizations\/([^/]+)\/projects\/([^/]+)\/builds$/);
+    if (req.method !== 'GET' || !buildsMatch) return false;
+    try {
+      let organizationSlug = decodeURIComponent(buildsMatch[1]);
+      let projectSlug = decodeURIComponent(buildsMatch[2]);
+      let limit = parsedUrl.searchParams.get('limit') || '20';
+      let branch = parsedUrl.searchParams.get('branch');
+      let queryParams = new URLSearchParams();
+      if (limit) queryParams.append('limit', limit);
+      if (branch) queryParams.append('branch', branch);
+      let query = queryParams.toString();
+      let endpoint = `/api/cli/organizations/${organizationSlug}/projects/${projectSlug}/builds${query ? `?${query}` : ''}`;
+      let response = await authService.authenticatedRequest(endpoint, {
+        method: 'GET'
+      });
+      sendSuccess(res, {
+        builds: response.builds || []
+      });
+    } catch (error) {
+      output.error('Error fetching builds from cloud:', error);
+      sendError(res, 500, error.message);
+    }
+    return true;
+  };
+}

package/dist/{commands/finalize.js → domains/builds/finalize.commands.js}

@@ -3,10 +3,11 @@
  * Uses functional API operations directly
  */
 
-import { createApiClient as defaultCreateApiClient, finalizeParallelBuild as defaultFinalizeParallelBuild } from '../api/index.js';
-import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
-import * as defaultOutput from '../utils/output.js';
-import { writeSession as defaultWriteSession } from '../utils/session.js';
+import * as defaultOutput from '../../shared/output.js';
+import { createApiClient as defaultCreateApiClient } from '../auth/cloud-client.js';
+import { loadConfig as defaultLoadConfig } from '../config/config-loader.js';
+import { writeSession as defaultWriteSession } from '../runs/session-store.js';
+import { finalizeParallelBuild as defaultFinalizeParallelBuild } from './build.service.js';
 let MISSING_BUILD_HINTS = ['  • No screenshots were uploaded with this parallel-id', '  • Tests were skipped or failed before capturing screenshots', '  • The parallel-id does not match what was used during test runs'];
 
 /**
@@ -150,17 +151,4 @@ export async function finalizeCommand(parallelId, options = {}, globalOptions =
   } finally {
     output.cleanup();
   }
-}
-
-/**
- * Validate finalize options
- * @param {string} parallelId - Parallel ID to finalize
- * @param {Object} options - Command options
- */
-export function validateFinalizeOptions(parallelId, _options) {
-  let errors = [];
-  if (!parallelId || parallelId.trim() === '') {
-    errors.push('Parallel ID is required');
-  }
-  return errors;
 }

package/dist/{commands/status.js → domains/builds/status.commands.js}

@@ -1,13 +1,17 @@
+import { getBuildReviewState, getComparisonStatus, getProcessingStatus, normalizeBuildStatus } from './build.normalizers.js';
+import { createStatusData, createStatusSuggestedCommands } from './build.serializers.js';
+
 /**
  * Status command implementation
  * Uses functional API operations directly
  */
 
-import { createApiClient as defaultCreateApiClient, getBuildStatus as defaultGetBuildStatus, getPreviewInfo as defaultGetPreviewInfo } from '../api/index.js';
-import { getAppBaseUrl } from '../utils/api-url.js';
-import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
-import * as defaultOutput from '../utils/output.js';
-import { getVisualReviewState } from '../utils/visual-context-normalizers.js';
+import { getAppBaseUrl } from '../../shared/api-url.js';
+import * as defaultOutput from '../../shared/output.js';
+import { createApiClient as defaultCreateApiClient } from '../auth/cloud-client.js';
+import { loadConfig as defaultLoadConfig } from '../config/config-loader.js';
+import { getPreviewInfo as defaultGetPreviewInfo } from '../previews/preview.service.js';
+import { getBuildStatus as defaultGetBuildStatus } from './build.service.js';
 function createStatusDeps(deps = {}) {
   return {
     loadConfig: deps.loadConfig || defaultLoadConfig,
@@ -48,108 +52,6 @@ async function fetchOptionalPreviewInfo(getPreviewInfo, client, buildId) {
     throw error;
   }
 }
-export function normalizeBuildStatus(buildStatus) {
-  return buildStatus.build;
-}
-
-/**
- * Read the processing counts from the status response.
- *
- * @param {Object} status - Status response.
- * @returns {Object} API-provided processing facts.
- */
-export function getProcessingStatus(status = {}) {
-  return status.processing;
-}
-
-/**
- * Read comparison totals without deriving them from screenshot counts.
- *
- * @param {Object} status - Status response.
- * @returns {Object} API-provided comparison facts.
- */
-export function getComparisonStatus(status = {}) {
-  return status.comparisons;
-}
-
-/**
- * Read the build review state without mixing it with processing status.
- *
- * @param {Object} status - Status response.
- * @returns {string|null} API-provided review state when available.
- */
-export function getBuildReviewState(status = {}) {
-  let build = normalizeBuildStatus(status);
-  return getVisualReviewState(build);
-}
-
-/**
- * Give agents concrete paths from lifecycle status into visual evidence.
- *
- * @param {Object} build - Build record from the status response.
- * @returns {{label: string, command: string}[]} Executable CLI commands.
- */
-export function createStatusSuggestedCommands(build = {}) {
-  if (!build.id) {
-    return [];
-  }
-  return [{
-    label: 'Discover build context API',
-    command: 'vizzly api schema sdk.getBuildContext --json'
-  }, {
-    label: 'List comparisons',
-    command: `vizzly --json comparisons --build ${build.id}`
-  }];
-}
-
-/**
- * Every lifecycle, processing, comparison, and review value comes directly
- * from the API.
- *
- * @param {Object} status - Status response.
- * @param {Object|null} previewInfo - Optional preview response.
- * @returns {Object} Machine-readable status payload.
- */
-export function createStatusData(status, previewInfo = null) {
-  let build = normalizeBuildStatus(status);
-  let processing = getProcessingStatus(status);
-  let comparisons = getComparisonStatus(status);
-  return {
-    resource: status.resource,
-    schemaVersion: status.schema_version,
-    buildId: build.id,
-    status: build.status,
-    conclusion: status.conclusion,
-    name: build.name,
-    createdAt: build.created_at,
-    updatedAt: build.updated_at,
-    completedAt: build.completed_at,
-    environment: build.environment,
-    branch: build.branch,
-    commit: build.commit_sha,
-    commitMessage: build.commit_message,
-    screenshotsTotal: processing.total,
-    processing,
-    comparisonsTotal: comparisons.total,
-    comparisons,
-    newComparisons: comparisons.new,
-    changedComparisons: comparisons.changed,
-    identicalComparisons: comparisons.identical,
-    visual_review: build.visual_review || null,
-    executionTime: build.execution_time_ms,
-    isBaseline: build.is_baseline,
-    userAgent: build.user_agent,
-    scope: status.scope,
-    links: status.links,
-    suggestedCommands: createStatusSuggestedCommands(build),
-    preview: previewInfo ? {
-      url: previewInfo.preview_url,
-      status: previewInfo.status,
-      fileCount: previewInfo.file_count,
-      expiresAt: previewInfo.expires_at
-    } : null
-  };
-}
 export function createBuildInfo(build) {
   let buildInfo = {
     Name: build.name || build.id,
@@ -490,17 +392,4 @@ export async function statusCommand(buildId, options = {}, globalOptions = {}, d
       error
     };
   }
-}
-
-/**
- * Validate status options
- * @param {string} buildId - Build ID to check
- * @param {Object} options - Command options
- */
-export function validateStatusOptions(buildId) {
-  let errors = [];
-  if (!buildId || buildId.trim() === '') {
-    errors.push('Build ID is required');
-  }
-  return errors;
 }

package/dist/domains/comparisons/cloud-comparisons.js

@@ -0,0 +1,43 @@
+import { buildEndpointWithParams } from '../../shared/cloud-protocol.js';
+import { VizzlyError } from '../../shared/vizzly-error.js';
+
+/**
+ * Get comparison information
+ * @param {Object} client - API client
+ * @param {string} comparisonId - Comparison ID
+ * @returns {Promise<Object>} Comparison data
+ */
+export async function getComparison(client, comparisonId) {
+  let response = await client.request(`/api/sdk/comparisons/${comparisonId}`);
+  return response.comparison;
+}
+
+/**
+ * Search for comparisons by name
+ * @param {Object} client - API client
+ * @param {string} name - Screenshot name to search for
+ * @param {Object} filters - Optional filters (branch, project, organization, limit, offset)
+ * @returns {Promise<Object>} Search results with comparisons and pagination
+ */
+export async function searchComparisons(client, name, filters = {}) {
+  if (!name || typeof name !== 'string') {
+    throw new VizzlyError('name is required and must be a non-empty string');
+  }
+  let {
+    branch,
+    project,
+    organization,
+    limit = 50,
+    offset = 0
+  } = filters;
+  let params = {
+    name,
+    limit: String(limit),
+    offset: String(offset)
+  };
+  if (branch) params.branch = branch;
+  if (project) params.project = project;
+  if (organization) params.organization = organization;
+  let endpoint = buildEndpointWithParams('/api/sdk/comparisons/search', params);
+  return client.request(endpoint);
+}

package/dist/{tdd/services/comparison-service.js → domains/comparisons/comparison.service.js}

@@ -5,7 +5,7 @@
  */
 
 import { analyze } from '@vizzly-testing/honeydiff';
-import { generateComparisonId } from '../core/signature.js';
+import { generateComparisonId } from '../screenshots/screenshot-identity.js';
 
 /**
  * Compare two images using honeydiff

package/dist/{commands/comparisons.js → domains/comparisons/comparisons.commands.js}

@@ -2,11 +2,13 @@
  * Comparisons command - query and search comparisons
  */
 
-import { createApiClient as defaultCreateApiClient, getBuild as defaultGetBuild, getComparison as defaultGetComparison, searchComparisons as defaultSearchComparisons } from '../api/index.js';
-import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
-import * as defaultOutput from '../utils/output.js';
-import { createWildcardMatcher } from '../utils/patterns.js';
-import { getComparisonBrowser, getComparisonName, getComparisonResult, getComparisonViewport } from '../utils/visual-context-normalizers.js';
+import * as defaultOutput from '../../shared/output.js';
+import { createWildcardMatcher } from '../../shared/patterns.js';
+import { createApiClient as defaultCreateApiClient } from '../auth/cloud-client.js';
+import { getBuild as defaultGetBuild } from '../builds/build.service.js';
+import { loadConfig as defaultLoadConfig } from '../config/config-loader.js';
+import { getComparisonBrowser, getComparisonName, getComparisonResult, getComparisonViewport } from '../context/context.normalizers.js';
+import { getComparison as defaultGetComparison, searchComparisons as defaultSearchComparisons } from './cloud-comparisons.js';
 
 /**
  * Comparisons command - query comparisons with various filters

package/dist/domains/config/config-defaults.js

@@ -0,0 +1,27 @@
+/**
+ * Default configuration values
+ */
+export let CONFIG_DEFAULTS = {
+  apiUrl: 'https://app.vizzly.dev',
+  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: []
+};

package/dist/{utils → domains/config}/config-discovery.js

@@ -1,6 +1,6 @@
-import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { cosmiconfigSync, defaultLoadersSync, getDefaultSearchPlacesSync } from 'cosmiconfig';
+import { readOptionalFile } from '../../shared/files.js';
 let searchPlaces = getDefaultSearchPlacesSync('vizzly');
 export function createConfigExplorer() {
   return cosmiconfigSync('vizzly', {
@@ -8,14 +8,6 @@ export function createConfigExplorer() {
     searchStrategy: 'none'
   });
 }
-export async function readOptionalFile(filename) {
-  try {
-    return await readFile(filename, 'utf8');
-  } catch (error) {
-    if (error.code === 'ENOENT') return null;
-    throw error;
-  }
-}
 export function configFormat(filename) {
   if (path.basename(filename) === 'package.json') return 'package';
   let extension = path.extname(filename);

package/dist/{utils → domains/config}/config-loader.js

@@ -1,11 +1,12 @@
 import { resolve } from 'node:path';
-import { CONFIG_DEFAULTS, deepMerge } from '../config/core.js';
+import * as output from '../../shared/output.js';
+import { getAccessToken } from '../auth/token-store.js';
+import { getProjectLink } from '../projects/project-link-store.js';
+import { deepMerge } from './config.normalizers.js';
+import { validateVizzlyConfigWithDefaults } from './config.validations.js';
+import { CONFIG_DEFAULTS } from './config-defaults.js';
 import { createConfigExplorer } from './config-discovery.js';
-import { validateVizzlyConfigWithDefaults } from './config-schema.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 { getProjectLink } from './project-link-store.js';
+import { getApiToken, getApiUrl, getBuildName, getMinClusterSize, getParallelId, getThreshold } from './environment.js';
 export async function loadConfig(configPath = null, cliOverrides = {}) {
   // 1. Load from config file using cosmiconfig
   let explorer = createConfigExplorer();
@@ -152,7 +153,7 @@ function applyCLIOverrides(config, cliOverrides = {}) {
   if (cliOverrides.allowNoToken !== undefined) config.allowNoToken = cliOverrides.allowNoToken;
 }
 function mergeConfig(target, source) {
-  for (const key in source) {
+  for (let key in source) {
     if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
       if (!target[key]) target[key] = {};
       mergeConfig(target[key], source[key]);
@@ -162,7 +163,7 @@ function mergeConfig(target, source) {
   }
 }
 export function getScreenshotPaths(config) {
-  const screenshotsDir = config.upload?.screenshotsDir || './screenshots';
-  const paths = Array.isArray(screenshotsDir) ? screenshotsDir : [screenshotsDir];
+  let screenshotsDir = config.upload?.screenshotsDir || './screenshots';
+  let paths = Array.isArray(screenshotsDir) ? screenshotsDir : [screenshotsDir];
   return paths.map(p => resolve(process.cwd(), p));
 }

package/dist/{commands/config-cmd.js → domains/config/config.commands.js}

@@ -1,11 +1,11 @@
+import * as defaultOutput from '../../shared/output.js';
+import { CONFIG_DEFAULTS } from './config-defaults.js';
+import { loadConfig as defaultLoadConfig } from './config-loader.js';
+
 /**
  * Config command - query and display configuration
  */
 
-import { CONFIG_DEFAULTS } from '../config/core.js';
-import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
-import * as defaultOutput from '../utils/output.js';
-
 /**
  * Config command - display current configuration
  * @param {string|null} key - Optional specific key to get (dot notation)

package/dist/{types → domains/config}/config.d.ts

@@ -4,7 +4,7 @@
  * @module @vizzly-testing/cli/config
  */
 
-export { VizzlyConfig } from './index';
+export { VizzlyConfig } from '../../index';
 
 /**
  * Define Vizzly configuration with type hints
@@ -26,5 +26,5 @@ export { VizzlyConfig } from './index';
  * });
  */
 export function defineConfig(
-  config: import('./index').VizzlyConfig
-): import('./index').VizzlyConfig;
+  config: import('../../index').VizzlyConfig
+): import('../../index').VizzlyConfig;

package/dist/domains/config/config.normalizers.js

@@ -0,0 +1,126 @@
+import { CONFIG_DEFAULTS } from './config-defaults.js';
+function isPlainConfigObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+function cloneConfigValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(cloneConfigValue);
+  }
+  if (isPlainConfigObject(value)) {
+    let cloned = {};
+    for (let key of Object.keys(value)) {
+      cloned[key] = cloneConfigValue(value[key]);
+    }
+    return cloned;
+  }
+  return value;
+}
+
+/**
+ * Deep merge two objects
+ * @param {Object} target - Target object
+ * @param {Object} source - Source object
+ * @returns {Object} Merged object (new object, inputs not mutated)
+ */
+export function deepMerge(target, source) {
+  let output = cloneConfigValue(target);
+  for (let key of Object.keys(source)) {
+    if (isPlainConfigObject(source[key])) {
+      if (isPlainConfigObject(target[key])) {
+        output[key] = deepMerge(target[key], source[key]);
+      } else {
+        output[key] = cloneConfigValue(source[key]);
+      }
+    } else {
+      output[key] = cloneConfigValue(source[key]);
+    }
+  }
+  return output;
+}
+
+/**
+ * Ensure value is a plain object, return empty object otherwise
+ * @param {*} value - Value to check
+ * @returns {Object} The value if it's an object, empty object otherwise
+ */
+function ensureObject(value) {
+  if (isPlainConfigObject(value)) {
+    return value;
+  }
+  return {};
+}
+function applyConfigLayer(config, sources, layer, sourceName) {
+  let merged = deepMerge(config, layer);
+  for (let key of Object.keys(layer)) {
+    sources[key] = sourceName;
+  }
+  return merged;
+}
+
+/**
+ * Build merged config from layers with source tracking
+ * @param {Object} options - Config layers
+ * @param {Object} options.projectConfig - Project config (from vizzly.config.js)
+ * @param {Object} options.globalConfig - Global config (from ~/.vizzly/config.json)
+ * @param {Object} [options.envOverrides] - Environment variable overrides
+ * @returns {{ config: Object, sources: Object }}
+ */
+export function buildMergedConfig({
+  projectConfig = {},
+  globalConfig = {},
+  envOverrides = {}
+} = {}) {
+  // Ensure all inputs are plain objects
+  let safeProjectConfig = ensureObject(projectConfig);
+  let safeGlobalConfig = ensureObject(globalConfig);
+  let safeEnvOverrides = ensureObject(envOverrides);
+  let mergedConfig = cloneConfigValue(CONFIG_DEFAULTS);
+  let sources = {};
+  for (let key of Object.keys(CONFIG_DEFAULTS)) {
+    sources[key] = 'default';
+  }
+  mergedConfig = applyConfigLayer(mergedConfig, sources, safeGlobalConfig, 'global');
+  mergedConfig = applyConfigLayer(mergedConfig, sources, safeProjectConfig, 'project');
+  mergedConfig = applyConfigLayer(mergedConfig, sources, safeEnvOverrides, 'env');
+  return {
+    config: mergedConfig,
+    sources
+  };
+}
+
+/**
+ * Extract environment variable overrides
+ * @param {Object} env - Environment variables object (defaults to process.env)
+ * @returns {Object} Overrides from environment
+ */
+export function extractEnvOverrides(env = process.env) {
+  let overrides = {};
+  if (env.VIZZLY_TOKEN) {
+    overrides.apiKey = env.VIZZLY_TOKEN;
+  }
+  if (env.VIZZLY_API_URL) {
+    overrides.apiUrl = env.VIZZLY_API_URL;
+  }
+  return overrides;
+}
+
+/**
+ * Extract config from cosmiconfig result (handles .default exports)
+ * @param {Object|null} result - Cosmiconfig result
+ * @returns {{ config: Object|null, filepath: string|null }}
+ */
+export function extractCosmiconfigResult(result) {
+  if (!result?.config) {
+    return {
+      config: null,
+      filepath: null
+    };
+  }
+
+  // Handle both `export default` and `module.exports`
+  let config = result.config.default || result.config;
+  return {
+    config,
+    filepath: result.filepath
+  };
+}