@vizzly-testing/cli 0.38.1 → 0.39.0

package/dist/server/handlers/tdd-handler.js

@@ -136,12 +136,20 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
   const tddService = new TddService(config, workingDir, setBaseline);
   const reportPath = join(workingDir, '.vizzly', 'report-data.json');
   const detailsPath = join(workingDir, '.vizzly', 'comparison-details.json');
+  let capture = {
+    accepted: 0,
+    rejected: 0
+  };
   let clearJsonFile = path => {
     if (existsSync(path)) {
       unlinkSync(path);
     }
   };
   let prepareRunArtifacts = () => {
+    capture = {
+      accepted: 0,
+      rejected: 0
+    };
     clearJsonFile(reportPath);
     clearJsonFile(detailsPath);
     tddService.clearRunData?.();
@@ -284,7 +292,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       output.debug('tdd', `baseline: ${baseline.buildName}`);
     }
   };
-  const handleScreenshot = async (_buildId, name, image, properties = {}, type, warnings = [], screenshotOptions = {}) => {
+  let processScreenshot = async (_buildId, name, image, properties = {}, type, warnings = [], screenshotOptions = {}) => {
     let handlerStart = Date.now();
     output.debug('tdd', `${name} received`);
 
@@ -411,6 +419,7 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       aaPixelsIgnored: comparison.aaPixelsIgnored,
       aaPercentage: comparison.aaPercentage,
       heightDiff: comparison.heightDiff,
+      heightChange: comparison.heightChange,
       error: comparison.error,
       warnings,
       originalName: name,
@@ -498,8 +507,30 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       }
     };
   };
+  let handleScreenshot = async (...args) => {
+    let result;
+    try {
+      result = await processScreenshot(...args);
+    } catch (error) {
+      result = {
+        statusCode: error.code === 'INVALID_IMAGE' ? 400 : 500,
+        body: {
+          error: error.message,
+          tddMode: true
+        }
+      };
+    }
+    if (result.statusCode >= 400) capture.rejected++;else capture.accepted++;
+    return result;
+  };
   const getResults = async () => {
-    return await tddService.printResults();
+    let results = await tddService.printResults();
+    return {
+      ...results,
+      capture: {
+        ...capture
+      }
+    };
   };
   const acceptBaseline = async comparisonId => {
     try {

package/dist/services/index.js

@@ -26,8 +26,14 @@ import { TestRunner } from './test-runner.js';
  * @returns {Object} Services object for plugins
  */
 export function createServices(config) {
-  let serverManager = createServerManager(config, {});
-  let testRunner = new TestRunner(config, serverManager);
+  // Direct programmatic config is explicit; loadConfig already distinguishes
+  // explicit comparison settings from its local fallback defaults.
+  let serviceConfig = {
+    ...config,
+    _comparisonOverrides: config._comparisonOverrides ?? config.comparison ?? {}
+  };
+  let serverManager = createServerManager(serviceConfig, {});
+  let testRunner = new TestRunner(serviceConfig, serverManager);
   return {
     serverManager,
     testRunner

package/dist/tdd/services/comparison-service.js

@@ -27,7 +27,8 @@ export async function compareImages(baselinePath, currentPath, diffPath, options
   let analysis = await analyze(baselinePath, currentPath, {
     threshold,
     antialiasing: true,
-    minimumRegionPixels: minClusterSize
+    minimumRegionPixels: minClusterSize,
+    alignHeightChanges: true
   }, {
     diffPath,
     overwrite: true
@@ -45,6 +46,7 @@ export async function compareImages(baselinePath, currentPath, diffPath, options
     aaPixelsIgnored: comparison.pixels.suppressed.antialiasing.count,
     aaPercentage: totalPixels > 0 ? comparison.pixels.suppressed.antialiasing.count / totalPixels * 100 : 0,
     boundingBox: comparison.difference.spatial?.bounds || null,
+    heightChange: heightChange || null,
     heightDiff: heightChange ? heightChange.direction === 'added' ? heightChange.rowCount : -heightChange.rowCount : 0,
     intensityStats: comparison.difference.appearance,
     diffClusters: comparison.difference.regions.map(region => ({
@@ -181,6 +183,7 @@ export function buildFailedComparison(params) {
     aaPercentage: honeydiffResult.aaPercentage,
     boundingBox: honeydiffResult.boundingBox,
     heightDiff: honeydiffResult.heightDiff,
+    heightChange: honeydiffResult.heightChange,
     intensityStats: honeydiffResult.intensityStats,
     diffClusters
   };

package/dist/tdd/tdd-service.js

@@ -9,8 +9,9 @@
  */
 
 import { existsSync as defaultExistsSync, mkdirSync as defaultMkdirSync, readFileSync as defaultReadFileSync, writeFileSync as defaultWriteFileSync } from 'node:fs';
+import { compareSync } from '@vizzly-testing/honeydiff';
 import { createApiClient as defaultCreateApiClient, getBuilds as defaultGetBuilds, getComparison as defaultGetComparison, getTddBaselines as defaultGetTddBaselines } from '../api/index.js';
-import { NetworkError } from '../errors/vizzly-error.js';
+import { NetworkError, VizzlyError } from '../errors/vizzly-error.js';
 import { colors as defaultColors } from '../utils/colors.js';
 import { fetchWithTimeout as defaultFetchWithTimeout } from '../utils/fetch-utils.js';
 import { getDefaultBranch as defaultGetDefaultBranch } from '../utils/git.js';
@@ -809,6 +810,17 @@ export class TddService {
     let currentImagePath = getCurrentPath(this.currentPath, filename);
     let baselineImagePath = getBaselinePath(this.baselinePath, filename);
     let diffImagePath = getDiffPath(this.diffPath, filename);
+    let hasBaseline = baselineExists(this.baselinePath, filename);
+
+    // Existing baselines are decoded by normal comparison. New or explicitly
+    // replaced baselines need the same validation before persisting any bytes.
+    if (this.setBaseline || !hasBaseline) {
+      try {
+        compareSync(imageBuffer, imageBuffer);
+      } catch (error) {
+        throw new VizzlyError(`Invalid screenshot image: ${error.message}`, 'INVALID_IMAGE');
+      }
+    }
 
     // Save current screenshot
     saveCurrent(this.currentPath, filename, imageBuffer);
@@ -819,7 +831,7 @@ export class TddService {
     }
 
     // Check if baseline exists
-    if (!baselineExists(this.baselinePath, filename)) {
+    if (!hasBaseline) {
       // Create new baseline
       saveBaseline(this.baselinePath, filename, imageBuffer);
 

package/dist/test-runner/core.js

@@ -119,11 +119,20 @@ export function determineBuildMode(tdd) {
  * Build result object for disabled run (no Vizzly integration)
  * @returns {Object} Result object
  */
-export function buildDisabledRunResult() {
+export function buildDisabledRunResult(reason = null) {
   return {
     testsPassed: 1,
     testsFailed: 0,
-    screenshotsCaptured: 0
+    screenshotsCaptured: 0,
+    ...(reason ? {
+      capture: {
+        setup: 'disabled',
+        reason,
+        accepted: 0,
+        rejected: 0,
+        errors: 0
+      }
+    } : {})
   };
 }
 
@@ -157,7 +166,23 @@ export function buildRunResult({
       uploads: uploadStats
     } : {}),
     comparisons: tddResults?.comparisons || null,
-    failed: (tddResults?.failed || 0) > 0
+    failed: (tddResults?.failed || 0) > 0,
+    ...(tddResults ? {
+      summary: {
+        total: tddResults.total ?? screenshotCount,
+        passed: tddResults.passed || 0,
+        failed: tddResults.failed || 0,
+        new: tddResults.new || 0,
+        errors: tddResults.errors || 0
+      },
+      capture: {
+        setup: 'ready',
+        reason: tddResults.error || null,
+        accepted: tddResults.capture?.accepted ?? screenshotCount,
+        rejected: tddResults.capture?.rejected || 0,
+        errors: tddResults.errors || 0
+      }
+    } : {})
   };
 }
 

package/dist/test-runner/operations.js

@@ -55,7 +55,7 @@ export async function createBuild({
     throw new Error('No API key available for build creation');
   }
   let client = createApiClient(clientOptions);
-  let payload = buildApiBuildPayload(runOptions, config.comparison);
+  let payload = buildApiBuildPayload(runOptions, config._comparisonOverrides);
   let buildResult = await createApiBuild(client, payload);
   if (!buildResult?.id) {
     throw new Error('Vizzly API did not return a build ID');
@@ -242,22 +242,31 @@ export function executeTestCommand({
 async function executeDisabledTestRun({
   testCommand,
   json,
+  reason,
   deps
 }) {
   let {
     spawn,
     createError
   } = deps;
-  await executeTestCommand({
-    command: testCommand,
-    env: buildDisabledEnv(),
-    json,
-    deps: {
-      spawn,
-      createError
-    }
-  });
-  return buildDisabledRunResult();
+  let result = buildDisabledRunResult(reason);
+  try {
+    await executeTestCommand({
+      command: testCommand,
+      env: buildDisabledEnv(),
+      json,
+      deps: {
+        spawn,
+        createError
+      }
+    });
+  } catch (error) {
+    result.testsPassed = 0;
+    result.testsFailed = 1;
+    error.runResult = result;
+    throw error;
+  }
+  return result;
 }
 
 // ============================================================================
@@ -389,6 +398,7 @@ export async function runTests({
     return executeDisabledTestRun({
       testCommand,
       json: runOptions.json,
+      reason: error.message,
       deps: {
         spawn,
         createError
@@ -430,6 +440,15 @@ export async function runTests({
       output.debug('tdd', 'failed to get results', {
         error: tddError.message
       });
+      tddResults = {
+        total: 0,
+        errors: 1,
+        error: tddError.message,
+        capture: {
+          accepted: 0,
+          rejected: 0
+        }
+      };
     }
   }
 
@@ -474,23 +493,25 @@ export async function runTests({
       output.error('Failed to stop server:', stopError);
     }
   }
+  let result = buildRunResult({
+    buildId,
+    buildUrl,
+    testSuccess,
+    screenshotCount,
+    tddResults,
+    uploadStats
+  });
 
-  // Throw test error after cleanup
+  // Throw test error after cleanup, retaining any completed visual evidence.
   if (testError) {
     if (!runOptions.json) {
       output.error('Test run failed:', testError);
     }
     if (uploadStats) testError.uploads = uploadStats;
+    if (tdd) testError.runResult = result;
     throw testError;
   }
-  return buildRunResult({
-    buildId,
-    buildUrl,
-    testSuccess,
-    screenshotCount,
-    tddResults,
-    uploadStats
-  });
+  return result;
 }
 
 /**

package/dist/types/index.d.ts

@@ -48,9 +48,16 @@ export interface TddConfig {
   openReport?: boolean;
 }
 
+export interface ProjectConfig {
+  organizationSlug: string;
+  projectSlug: string;
+}
+
 export interface VizzlyConfig {
   apiKey?: string;
   apiUrl?: string;
+  /** Nonsecret repository destination. Upload credentials stay in user storage. */
+  project?: ProjectConfig;
   server?: ServerConfig;
   build?: BuildConfig;
   upload?: UploadConfig;
@@ -131,6 +138,7 @@ export interface TddResults {
   failed: number;
   new: number;
   errors: number;
+  capture?: { accepted: number; rejected: number };
   comparisons: ComparisonResult[];
   baseline: BaselineData | null;
 }

package/dist/uploader/core.js

@@ -206,6 +206,7 @@ export function fileToScreenshotFormat(file) {
   return {
     sha256: file.sha256,
     name: file.filename.replace(/\.png$/, ''),
+    filename: file.filename,
     properties: browser ? {
       browser
     } : {}

package/dist/utils/config-discovery.js

@@ -0,0 +1,73 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { cosmiconfigSync, defaultLoadersSync, getDefaultSearchPlacesSync } from 'cosmiconfig';
+let searchPlaces = getDefaultSearchPlacesSync('vizzly');
+export function createConfigExplorer() {
+  return cosmiconfigSync('vizzly', {
+    searchPlaces,
+    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);
+  if (extension === '.json') return 'json';
+  if (extension === '.ts') return 'typescript';
+  if (extension === '.js') return 'javascript';
+  if (extension === '.cjs') return 'commonjs';
+  if (['.yaml', '.yml', ''].includes(extension)) return 'yaml';
+  return 'unknown';
+}
+async function inspectConfig(filename, allowInvalid) {
+  let source = await readOptionalFile(filename);
+  let result = {
+    configPath: filename,
+    exists: source !== null,
+    format: configFormat(filename),
+    source
+  };
+  if (source === null) return result;
+  try {
+    if (result.format === 'package') {
+      result.packageConfig = JSON.parse(source);
+      result.parsedConfig = result.packageConfig.vizzly;
+    } else if (result.format === 'json') {
+      result.parsedConfig = JSON.parse(source);
+    } else if (result.format === 'yaml') {
+      result.parsedConfig = defaultLoadersSync.noExt(filename, source);
+    }
+  } catch (error) {
+    // Replacing a standalone file does not need its old values. Package config
+    // still needs valid JSON so unrelated scripts and dependencies survive.
+    if (!allowInvalid || result.format === 'package') throw error;
+    result.parseError = error.message;
+  }
+  return result;
+}
+
+// Setup discovers source files without evaluating executable configuration or
+// reading credentials. Runtime loading remains the explorer's responsibility.
+export async function discoverConfig({
+  cwd = process.cwd(),
+  configPath = null,
+  allowInvalid = false
+} = {}) {
+  if (configPath) return inspectConfig(path.resolve(cwd, configPath), allowInvalid);
+  for (let place of searchPlaces) {
+    let candidate = await inspectConfig(path.resolve(cwd, place), allowInvalid);
+    if (!candidate.exists || !candidate.source.trim()) continue;
+    if (['package', 'json', 'yaml'].includes(candidate.format) && candidate.parsedConfig == null && !candidate.parseError) {
+      continue;
+    }
+    return candidate;
+  }
+  return inspectConfig(path.resolve(cwd, 'vizzly.config.js'), allowInvalid);
+}

package/dist/utils/config-loader.js

@@ -1,14 +1,14 @@
 import { resolve } from 'node:path';
-import { cosmiconfigSync } from 'cosmiconfig';
 import { CONFIG_DEFAULTS, deepMerge } from '../config/core.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 { getActiveProjectLink } from './project-link-store.js';
+import { getProjectLink } from './project-link-store.js';
 export async function loadConfig(configPath = null, cliOverrides = {}) {
   // 1. Load from config file using cosmiconfig
-  let explorer = cosmiconfigSync('vizzly');
+  let explorer = createConfigExplorer();
   let result = configPath ? explorer.load(configPath) : explorer.search();
   let fileConfig = {};
   if (result?.config) {
@@ -18,6 +18,12 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
 
   // 2. Validate config file using Zod schema
   let validatedFileConfig = validateVizzlyConfigWithDefaults(fileConfig);
+  let comparisonOverrides = {};
+  for (let key of ['threshold', 'minClusterSize']) {
+    if (fileConfig.comparison?.[key] !== undefined) {
+      comparisonOverrides[key] = validatedFileConfig.comparison[key];
+    }
+  }
 
   // Create a proper clone of the default config to avoid shared object references
   let config = deepMerge(CONFIG_DEFAULTS, {});
@@ -42,9 +48,13 @@ 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 (envThreshold !== undefined) {
+    config.comparison.threshold = envThreshold;
+    comparisonOverrides.threshold = envThreshold;
+  }
   if (envMinClusterSize !== undefined) {
     config.comparison.minClusterSize = envMinClusterSize;
+    comparisonOverrides.minClusterSize = envMinClusterSize;
   }
 
   // 4. Apply CLI overrides (highest priority)
@@ -52,11 +62,21 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
     output.debug('config', 'using token from --token flag');
   }
   applyCLIOverrides(config, cliOverrides);
+  for (let key of ['threshold', 'minClusterSize']) {
+    if (cliOverrides[key] !== undefined) {
+      comparisonOverrides[key] = config.comparison[key];
+    }
+  }
+  let validatedComparison = validateVizzlyConfigWithDefaults({
+    comparison: comparisonOverrides
+  }).comparison;
+  config._comparisonOverrides = Object.fromEntries(Object.keys(comparisonOverrides).map(key => [key, validatedComparison[key]]));
 
-  // 5. Fall back to a linked project token for cloud upload commands.
-  if (!config.apiKey) {
-    let linkedProject = await getActiveProjectLink({
-      apiUrl: config.apiUrl
+  // 5. Use only the credential belonging to this repository's destination.
+  if (!config.apiKey && config.project) {
+    let linkedProject = await getProjectLink({
+      apiUrl: config.apiUrl,
+      ...config.project
     });
     if (linkedProject?.token) {
       config.apiKey = linkedProject.token;
@@ -83,6 +103,7 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
     output.debug('config', 'using user login for user-authenticated commands');
   }
   config._configPath = result?.filepath || null;
+  config._configApiUrl = validatedFileConfig.apiUrl;
   return config;
 }
 

package/dist/utils/config-schema.js

@@ -50,6 +50,10 @@ const comparisonSchema = z.object({
 const tddSchema = z.object({
   openReport: z.boolean().default(CONFIG_DEFAULTS.tdd.openReport)
 });
+let projectSchema = z.object({
+  organizationSlug: z.string().trim().min(1),
+  projectSlug: z.string().trim().min(1)
+});
 
 /**
  * Core Vizzly configuration schema
@@ -59,6 +63,7 @@ export const vizzlyConfigSchema = z.object({
   // Core Vizzly config
   apiKey: z.string().optional(),
   apiUrl: z.string().url().default(CONFIG_DEFAULTS.apiUrl),
+  project: projectSchema.optional(),
   server: serverSchema.default(CONFIG_DEFAULTS.server),
   build: buildSchema.default(CONFIG_DEFAULTS.build),
   upload: uploadSchema.default(CONFIG_DEFAULTS.upload),

package/dist/utils/file-changes.js

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { access, lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { readOptionalFile } from './config-discovery.js';
+export async function fileChange(filename, after) {
+  let before = await readOptionalFile(filename);
+  return before === after ? null : {
+    path: filename,
+    before,
+    after
+  };
+}
+async function writableParent(filename) {
+  let parent = path.dirname(filename);
+  while (true) {
+    try {
+      await access(parent, constants.W_OK);
+      return;
+    } catch (error) {
+      if (error.code !== 'ENOENT' || path.dirname(parent) === parent) {
+        throw error;
+      }
+      parent = path.dirname(parent);
+    }
+  }
+}
+async function checkChange(change) {
+  // Reject redirects in parent folders too, including explicit config paths.
+  // Top-level OS aliases such as /tmp on macOS are safe to follow.
+  for (let parent = path.dirname(change.path); path.dirname(parent) !== parent; parent = path.dirname(parent)) {
+    try {
+      if (path.dirname(parent) !== path.parse(parent).root && (await lstat(parent)).isSymbolicLink()) {
+        throw new Error(`Setup will not write through a symlink: ${parent}`);
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  let info;
+  try {
+    info = await lstat(change.path);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  if (info?.isSymbolicLink()) {
+    throw new Error(`Setup will not replace a symlink: ${change.path}`);
+  }
+  let current = await readOptionalFile(change.path);
+  if (current !== change.before) {
+    throw new Error(`${change.path} changed during setup; run init again.`);
+  }
+  if (current !== null) {
+    if (!info.isFile()) {
+      throw new Error(`Setup needs a regular file: ${change.path}`);
+    }
+    await access(change.path, constants.W_OK);
+  }
+  await writableParent(change.path);
+}
+export async function preflightChanges(changes) {
+  for (let change of changes.filter(Boolean)) await checkChange(change);
+}
+export async function applyChanges(changes) {
+  let planned = changes.filter(Boolean);
+  await preflightChanges(planned);
+  let completed = [];
+  try {
+    for (let change of planned) {
+      await checkChange(change);
+      await mkdir(path.dirname(change.path), {
+        recursive: true
+      });
+      if (change.before === null) {
+        await writeFile(change.path, change.after, {
+          flag: 'wx'
+        });
+      } else {
+        let temporary = `${change.path}.${randomUUID()}.tmp`;
+        try {
+          let {
+            mode
+          } = await lstat(change.path);
+          await writeFile(temporary, change.after, {
+            flag: 'wx',
+            mode
+          });
+          await rename(temporary, change.path);
+        } finally {
+          await rm(temporary, {
+            force: true
+          });
+        }
+      }
+      completed.push({
+        path: change.path,
+        status: 'written'
+      });
+    }
+  } catch (error) {
+    error.completed = completed;
+    throw error;
+  }
+  return completed;
+}