@vizzly-testing/cli 0.23.1 → 0.23.2

package/dist/api/client.js

@@ -78,7 +78,9 @@ export function createApiClient(options = {}) {
 
       // Other errors
       let error = parseApiError(response.status, errorBody, url);
-      throw new VizzlyError(error.message, error.code);
+      throw new VizzlyError(error.message, error.code, {
+        status: error.status
+      });
     }
     return response.json();
   }

package/dist/api/endpoints.js

@@ -325,17 +325,16 @@ export async function finalizeParallelBuild(client, parallelId) {
  * @returns {Promise<Object>} Upload result with preview URL
  */
 export async function uploadPreviewZip(client, buildId, zipBuffer) {
-  // Create form data with the ZIP file
-  let FormData = (await import('form-data')).default;
+  // Use native FormData (Node 18+) with Blob for proper fetch compatibility
   let formData = new FormData();
-  formData.append('file', zipBuffer, {
-    filename: 'preview.zip',
-    contentType: 'application/zip'
+  let blob = new Blob([zipBuffer], {
+    type: 'application/zip'
   });
+  formData.append('file', blob, 'preview.zip');
   return client.request(`/api/sdk/builds/${buildId}/preview/upload-zip`, {
     method: 'POST',
-    body: formData,
-    headers: formData.getHeaders()
+    body: formData
+    // Let fetch set the Content-Type with boundary automatically
   });
 }
 

package/dist/cli.js

@@ -63,7 +63,7 @@ const formatHelp = (cmd, helper) => {
         key: 'core',
         icon: '▸',
         title: 'Core',
-        names: ['run', 'tdd', 'upload', 'status', 'finalize']
+        names: ['run', 'tdd', 'upload', 'status', 'finalize', 'preview']
       }, {
         key: 'setup',
         icon: '▸',
@@ -412,9 +412,22 @@ program.command('finalize').description('Finalize a parallel build after all sha
   }
   await finalizeCommand(parallelId, options, globalOptions);
 });
-program.command('preview').description('Upload static files as a preview for a build').argument('<path>', 'Path to static files (dist/, build/, out/)').option('-b, --build <id>', 'Build ID to attach preview to').option('-p, --parallel-id <id>', 'Look up build by parallel ID').option('--base <path>', 'Override auto-detected base path').option('--open', 'Open preview URL in browser after upload').action(async (path, options) => {
+program.command('preview').description('Upload static files as a preview for a build').argument('[path]', 'Path to static files (dist/, build/, out/)').option('-b, --build <id>', 'Build ID to attach preview to').option('-p, --parallel-id <id>', 'Look up build by parallel ID').option('--base <path>', 'Override auto-detected base path').option('--open', 'Open preview URL in browser after upload').option('--dry-run', 'Show what would be uploaded without uploading').option('-x, --exclude <pattern>', 'Exclude files/dirs (repeatable, e.g. -x "*.log" -x "temp/")', (val, prev) => prev ? [...prev, val] : [val]).option('-i, --include <pattern>', 'Override default exclusions (repeatable, e.g. -i package.json -i tests/)', (val, prev) => prev ? [...prev, val] : [val]).action(async (path, options) => {
   const globalOptions = program.opts();
 
+  // Show helpful error if path is missing
+  if (!path) {
+    output.error('Path to static files is required');
+    output.blank();
+    output.print('  Upload your build output directory:');
+    output.blank();
+    output.print('    vizzly preview ./dist');
+    output.print('    vizzly preview ./build');
+    output.print('    vizzly preview ./out');
+    output.blank();
+    process.exit(1);
+  }
+
   // Validate options
   const validationErrors = validatePreviewOptions(path, options);
   if (validationErrors.length > 0) {

package/dist/commands/finalize.js

@@ -89,6 +89,18 @@ export async function finalizeCommand(parallelId, options = {}, globalOptions =
     };
   } catch (error) {
     output.stopSpinner();
+
+    // Don't fail CI for Vizzly infrastructure issues (5xx errors)
+    let status = error.context?.status;
+    if (status >= 500) {
+      output.warn('Vizzly API unavailable - finalize skipped.');
+      return {
+        success: true,
+        result: {
+          skipped: true
+        }
+      };
+    }
     output.error('Failed to finalize parallel build', error);
     exit(1);
     return {

package/dist/commands/preview.js

@@ -20,6 +20,9 @@ import * as defaultOutput from '../utils/output.js';
 import { formatSessionAge as defaultFormatSessionAge, readSession as defaultReadSession } from '../utils/session.js';
 let execAsync = promisify(exec);
 
+// Maximum files to show in dry-run output (use --verbose for all)
+let DRY_RUN_FILE_LIMIT = 50;
+
 /**
  * Validate path for shell safety - prevents command injection
  * @param {string} path - Path to validate
@@ -74,17 +77,49 @@ function getZipCommand() {
   };
 }
 
+// Default directories to exclude from preview uploads
+let DEFAULT_EXCLUDED_DIRS = ['node_modules', '__pycache__', '.git', '.svn', '.hg', '.vizzly', 'coverage', '.nyc_output', '.cache', '.turbo', '.next/cache', '.nuxt', '.output', '.vercel', '.netlify', 'tests', 'test', '__tests__', 'spec', '__mocks__', 'playwright-report', 'cypress', '.playwright'];
+
+// Default file patterns to exclude from preview uploads
+let DEFAULT_EXCLUDED_FILES = ['package.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lockb', '*.config.js', '*.config.ts', '*.config.mjs', '*.config.cjs', 'tsconfig.json', 'jsconfig.json', '.eslintrc*', '.prettierrc*', 'Makefile', 'Dockerfile', 'docker-compose*.yml', '*.md', '*.log', '*.map'];
+
+/**
+ * Check if a filename matches any of the exclusion patterns
+ * @param {string} filename - Filename to check
+ * @param {string[]} patterns - Patterns to match against
+ * @returns {boolean}
+ */
+function matchesPattern(filename, patterns) {
+  for (let pattern of patterns) {
+    if (pattern.includes('*')) {
+      // Simple glob matching - convert to regex
+      let regex = new RegExp(`^${pattern.replace(/\./g, '\\.').replace(/\*/g, '.*')}$`);
+      if (regex.test(filename)) return true;
+    } else {
+      if (filename === pattern) return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Create a ZIP file from a directory using system commands
  * @param {string} sourceDir - Directory to zip
  * @param {string} outputPath - Path for output ZIP file
+ * @param {Object} exclusions - Exclusion patterns
+ * @param {string[]} exclusions.dirs - Directory names to exclude
+ * @param {string[]} exclusions.files - File patterns to exclude
  * @returns {Promise<void>}
  */
-async function createZipWithSystem(sourceDir, outputPath) {
+async function createZipWithSystem(sourceDir, outputPath, exclusions = {}) {
   let {
     command,
     available
   } = getZipCommand();
+  let {
+    dirs = [],
+    files = []
+  } = exclusions;
   if (!available) {
     throw new Error('No zip command found. Please install zip or use PowerShell on Windows.');
   }
@@ -95,22 +130,44 @@ async function createZipWithSystem(sourceDir, outputPath) {
   if (!isPathSafe(sourceDir)) {
     throw new Error('Path contains unsupported characters. Please use a path without special shell characters.');
   }
+
+  // Validate exclusion patterns to prevent command injection
+  // Only allow safe characters in patterns: alphanumeric, dots, asterisks, underscores, hyphens, slashes
+  let safePatternRegex = /^[a-zA-Z0-9.*_\-/]+$/;
+  for (let pattern of [...dirs, ...files]) {
+    if (!safePatternRegex.test(pattern)) {
+      throw new Error(`Exclusion pattern contains unsafe characters: ${pattern}. Only alphanumeric, ., *, _, -, / are allowed.`);
+    }
+  }
   if (command === 'zip') {
     // Standard zip command - create ZIP from directory contents
     // Using cwd option is safe as it's not part of the command string
-    // -r: recursive, -q: quiet
-    await execAsync(`zip -r -q "${outputPath}" .`, {
+    // -r: recursive, -q: quiet, -x: exclude patterns
+    let excludeArgs = [...dirs.map(dir => `-x "${dir}/*"`), ...files.map(pattern => `-x "${pattern}"`)].join(' ');
+    await execAsync(`zip -r -q "${outputPath}" . ${excludeArgs}`, {
       cwd: sourceDir,
       maxBuffer: 1024 * 1024 * 100 // 100MB buffer
     });
   } else if (command === 'powershell') {
-    // Windows PowerShell - use -LiteralPath for safer path handling
-    // Escape single quotes in paths by doubling them
+    // Windows PowerShell - Compress-Archive doesn't support exclusions,
+    // so we create a temp directory with only the files we want
     let safeSrcDir = sourceDir.replace(/'/g, "''");
     let safeOutPath = outputPath.replace(/'/g, "''");
-    await execAsync(`powershell -Command "Compress-Archive -LiteralPath '${safeSrcDir}\\*' -DestinationPath '${safeOutPath}' -Force"`, {
-      maxBuffer: 1024 * 1024 * 100
-    });
+
+    // Build exclusion filter for PowerShell
+    // We use Get-ChildItem with -Exclude and pipe to Compress-Archive
+    let excludePatterns = [...dirs, ...files].map(p => `'${p}'`).join(',');
+    if (excludePatterns) {
+      // Use robocopy to copy files excluding patterns, then zip
+      // This is more reliable than PowerShell's native filtering
+      await execAsync(`powershell -Command "` + `$src = '${safeSrcDir}'; ` + `$dst = '${safeOutPath}'; ` + `$exclude = @(${excludePatterns}); ` + `$items = Get-ChildItem -Path $src -Recurse -File | Where-Object { ` + `$rel = $_.FullName.Substring($src.Length + 1); ` + `$dominated = $false; ` + `foreach ($ex in $exclude) { if ($rel -like $ex -or $rel -like \\"$ex/*\\" -or $_.Name -like $ex) { $dominated = $true; break } }; ` + `-not $dominated ` + `}; ` + `if ($items) { $items | Compress-Archive -DestinationPath $dst -Force }"`, {
+        maxBuffer: 1024 * 1024 * 100
+      });
+    } else {
+      await execAsync(`powershell -Command "Compress-Archive -LiteralPath '${safeSrcDir}\\*' -DestinationPath '${safeOutPath}' -Force"`, {
+        maxBuffer: 1024 * 1024 * 100
+      });
+    }
   }
 }
 
@@ -118,14 +175,24 @@ async function createZipWithSystem(sourceDir, outputPath) {
  * Count files in a directory recursively
  * Skips symlinks to prevent path traversal attacks
  * @param {string} dir - Directory path
- * @returns {Promise<{ count: number, totalSize: number }>}
+ * @param {Object} options - Options
+ * @param {boolean} options.collectPaths - Whether to collect file paths
+ * @param {string[]} options.excludedDirs - Directory names to exclude
+ * @param {string[]} options.excludedFiles - File patterns to exclude
+ * @returns {Promise<{ count: number, totalSize: number, files?: Array<{path: string, size: number}> }>}
  */
-async function countFiles(dir) {
+async function countFiles(dir, options = {}) {
   let {
     readdir
   } = await import('node:fs/promises');
+  let {
+    collectPaths = false,
+    excludedDirs = DEFAULT_EXCLUDED_DIRS,
+    excludedFiles = DEFAULT_EXCLUDED_FILES
+  } = options;
   let count = 0;
   let totalSize = 0;
+  let files = collectPaths ? [] : null;
 
   // Resolve the base directory to an absolute path for traversal checks
   let baseDir = await realpath(resolve(dir));
@@ -141,8 +208,8 @@ async function countFiles(dir) {
         continue;
       }
       if (entry.isDirectory()) {
-        // Skip hidden directories and common non-content directories
-        if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === '__pycache__') {
+        // Skip hidden directories and excluded directories
+        if (entry.name.startsWith('.') || excludedDirs.includes(entry.name)) {
           continue;
         }
 
@@ -157,16 +224,30 @@ async function countFiles(dir) {
         if (entry.name.startsWith('.')) {
           continue;
         }
+
+        // Skip excluded file patterns
+        if (matchesPattern(entry.name, excludedFiles)) {
+          continue;
+        }
         count++;
         let fileStat = await stat(fullPath);
         totalSize += fileStat.size;
+        if (files) {
+          // Store relative path from base directory
+          let relativePath = fullPath.slice(baseDir.length + 1);
+          files.push({
+            path: relativePath,
+            size: fileStat.size
+          });
+        }
       }
     }
   }
   await walk(baseDir);
   return {
     count,
-    totalSize
+    totalSize,
+    files
   };
 }
 
@@ -213,8 +294,8 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
     };
     let config = await loadConfig(globalOptions.config, allOptions);
 
-    // Validate API token
-    if (!config.apiKey) {
+    // Validate API token (skip for dry-run)
+    if (!options.dryRun && !config.apiKey) {
       output.error('API token required. Use --token or set VIZZLY_TOKEN environment variable');
       exit(1);
       return {
@@ -296,23 +377,64 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
       };
     }
 
-    // Check for zip command availability
-    let zipInfo = getZipCommand();
-    if (!zipInfo.available) {
-      output.error('No zip command found. Please install zip (macOS/Linux) or ensure PowerShell is available (Windows).');
-      exit(1);
-      return {
-        success: false,
-        reason: 'no-zip-command'
-      };
+    // Check for zip command availability (skip for dry-run)
+    if (!options.dryRun) {
+      let zipInfo = getZipCommand();
+      if (!zipInfo.available) {
+        output.error('No zip command found. Please install zip (macOS/Linux) or ensure PowerShell is available (Windows).');
+        exit(1);
+        return {
+          success: false,
+          reason: 'no-zip-command'
+        };
+      }
+    }
+
+    // Build exclusion lists from defaults and user options
+    let excludedDirs = [...DEFAULT_EXCLUDED_DIRS];
+    let excludedFiles = [...DEFAULT_EXCLUDED_FILES];
+
+    // Add user-specified exclusions
+    if (options.exclude) {
+      let userExcludes = Array.isArray(options.exclude) ? options.exclude : [options.exclude];
+      for (let pattern of userExcludes) {
+        // If pattern ends with /, treat as directory
+        if (pattern.endsWith('/')) {
+          excludedDirs.push(pattern.slice(0, -1));
+        } else {
+          excludedFiles.push(pattern);
+        }
+      }
     }
 
+    // Remove patterns that user explicitly wants to include
+    if (options.include) {
+      let userIncludes = Array.isArray(options.include) ? options.include : [options.include];
+      for (let pattern of userIncludes) {
+        if (pattern.endsWith('/')) {
+          let dirName = pattern.slice(0, -1);
+          excludedDirs = excludedDirs.filter(d => d !== dirName);
+        } else {
+          excludedFiles = excludedFiles.filter(f => f !== pattern);
+        }
+      }
+    }
+    let exclusions = {
+      dirs: excludedDirs,
+      files: excludedFiles
+    };
+
     // Count files and calculate size
     output.startSpinner('Scanning files...');
     let {
       count: fileCount,
-      totalSize
-    } = await countFiles(path);
+      totalSize,
+      files
+    } = await countFiles(path, {
+      collectPaths: options.dryRun,
+      excludedDirs,
+      excludedFiles
+    });
     if (fileCount === 0) {
       output.stopSpinner();
       output.error(`No files found in ${path}`);
@@ -322,7 +444,67 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
         reason: 'no-files'
       };
     }
-    output.updateSpinner(`Found ${fileCount} files (${formatBytes(totalSize)})`);
+    output.stopSpinner();
+
+    // Dry run - show what would be uploaded and exit
+    if (options.dryRun) {
+      let colors = output.getColors();
+      if (globalOptions.json) {
+        output.data({
+          dryRun: true,
+          path: resolve(path),
+          fileCount,
+          totalSize,
+          excludedDirs,
+          excludedFiles,
+          files: files.map(f => ({
+            path: f.path,
+            size: f.size
+          }))
+        });
+      } else {
+        output.info(`Dry run - would upload ${fileCount} files (${formatBytes(totalSize)})`);
+        output.blank();
+        output.print(`  ${colors.brand.textTertiary('Source')}      ${resolve(path)}`);
+        output.print(`  ${colors.brand.textTertiary('Files')}       ${fileCount}`);
+        output.print(`  ${colors.brand.textTertiary('Total size')}  ${formatBytes(totalSize)}`);
+        output.blank();
+
+        // Show exclusions in verbose mode
+        if (globalOptions.verbose) {
+          output.print(`  ${colors.brand.textTertiary('Excluded directories:')}`);
+          for (let dir of excludedDirs) {
+            output.print(`    ${colors.dim(dir)}`);
+          }
+          output.blank();
+          output.print(`  ${colors.brand.textTertiary('Excluded file patterns:')}`);
+          for (let pattern of excludedFiles) {
+            output.print(`    ${colors.dim(pattern)}`);
+          }
+          output.blank();
+        }
+
+        // Show files (limit in non-verbose mode)
+        let displayFiles = globalOptions.verbose ? files : files.slice(0, DRY_RUN_FILE_LIMIT);
+        let hasMore = files.length > displayFiles.length;
+        output.print(`  ${colors.brand.textTertiary('Files to upload:')}`);
+        for (let file of displayFiles) {
+          output.print(`    ${file.path} ${colors.dim(`(${formatBytes(file.size)})`)}`);
+        }
+        if (hasMore) {
+          output.print(`    ${colors.dim(`... and ${files.length - DRY_RUN_FILE_LIMIT} more (use --verbose to see all)`)}`);
+        }
+      }
+      output.cleanup();
+      return {
+        success: true,
+        dryRun: true,
+        fileCount,
+        totalSize,
+        files
+      };
+    }
+    output.startSpinner(`Found ${fileCount} files (${formatBytes(totalSize)})`);
 
     // Create ZIP using system command
     output.updateSpinner('Compressing files...');
@@ -331,7 +513,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
     let zipPath = join(tmpdir(), `vizzly-preview-${Date.now()}-${randomSuffix}.zip`);
     let zipBuffer;
     try {
-      await createZipWithSystem(path, zipPath);
+      await createZipWithSystem(path, zipPath, exclusions);
       zipBuffer = await readFile(zipPath);
     } catch (zipError) {
       output.stopSpinner();

package/dist/commands/run.js

@@ -356,6 +356,21 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
   } catch (error) {
     output.stopSpinner();
 
+    // Don't fail CI for Vizzly infrastructure issues (5xx errors)
+    let status = error.context?.status;
+    if (status >= 500) {
+      output.warn('Vizzly API unavailable - visual tests skipped. Your tests still ran.');
+      output.debug('api', 'API error details:', {
+        error: error.message
+      });
+      return {
+        success: true,
+        result: {
+          skipped: true
+        }
+      };
+    }
+
     // Provide more context about where the error occurred
     let errorContext = 'Test run failed';
     if (error.message?.includes('build')) {

package/dist/commands/status.js

@@ -3,18 +3,28 @@
  * Uses functional API operations directly
  */
 
-import { createApiClient, getBuild, getPreviewInfo } from '../api/index.js';
-import { loadConfig } from '../utils/config-loader.js';
-import { getApiUrl } from '../utils/environment-config.js';
-import * as output from '../utils/output.js';
+import { createApiClient as defaultCreateApiClient, getBuild as defaultGetBuild, getPreviewInfo as defaultGetPreviewInfo } from '../api/index.js';
+import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
+import { getApiUrl as defaultGetApiUrl } from '../utils/environment-config.js';
+import * as defaultOutput from '../utils/output.js';
 
 /**
  * Status command implementation
  * @param {string} buildId - Build ID to check status for
  * @param {Object} options - Command options
  * @param {Object} globalOptions - Global CLI options
+ * @param {Object} deps - Dependencies for testing
  */
-export async function statusCommand(buildId, options = {}, globalOptions = {}) {
+export async function statusCommand(buildId, options = {}, globalOptions = {}, deps = {}) {
+  let {
+    loadConfig = defaultLoadConfig,
+    createApiClient = defaultCreateApiClient,
+    getBuild = defaultGetBuild,
+    getPreviewInfo = defaultGetPreviewInfo,
+    getApiUrl = defaultGetApiUrl,
+    output = defaultOutput,
+    exit = code => process.exit(code)
+  } = deps;
   output.configure({
     json: globalOptions.json,
     verbose: globalOptions.verbose,
@@ -31,7 +41,7 @@ export async function statusCommand(buildId, options = {}, globalOptions = {}) {
     // Validate API token
     if (!config.apiKey) {
       output.error('API token required. Use --token or set VIZZLY_TOKEN environment variable');
-      process.exit(1);
+      exit(1);
     }
 
     // Get build details via functional API
@@ -194,11 +204,27 @@ export async function statusCommand(buildId, options = {}, globalOptions = {}) {
 
     // Exit with appropriate code based on build status
     if (build.status === 'failed' || build.failed_jobs > 0) {
-      process.exit(1);
+      exit(1);
     }
   } catch (error) {
+    // Don't fail CI for Vizzly infrastructure issues (5xx errors)
+    let status = error.context?.status;
+    if (status >= 500) {
+      output.warn('Vizzly API unavailable - status check skipped.');
+      output.cleanup();
+      return {
+        success: true,
+        result: {
+          skipped: true
+        }
+      };
+    }
     output.error('Failed to get build status', error);
-    process.exit(1);
+    exit(1);
+    return {
+      success: false,
+      error
+    };
   }
 }
 

package/dist/commands/upload.js

@@ -227,6 +227,19 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
       result
     };
   } catch (error) {
+    // Don't fail CI for Vizzly infrastructure issues (5xx errors)
+    let status = error.context?.status;
+    if (status >= 500) {
+      output.warn('Vizzly API unavailable - upload skipped. Your tests still ran.');
+      output.cleanup();
+      return {
+        success: true,
+        result: {
+          skipped: true
+        }
+      };
+    }
+
     // Mark build as failed if we have a buildId and config
     if (buildId && config) {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.23.1",
+  "version": "0.23.2",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -51,7 +51,6 @@
   "files": [
     "bin",
     "dist",
-    "docs",
     "claude-plugin",
     "README.md",
     "LICENSE"