@vizzly-testing/cli 0.19.0 → 0.19.2

package/dist/server/routers/baseline.js

@@ -12,13 +12,11 @@ import { sendError, sendServiceUnavailable, sendSuccess } from '../middleware/re
  * @param {Object} context - Router context
  * @param {Object} context.screenshotHandler - Screenshot handler
  * @param {Object} context.tddService - TDD service for baseline downloads
- * @param {Object} context.authService - Auth service for OAuth requests
  * @returns {Function} Route handler
  */
 export function createBaselineRouter({
   screenshotHandler,
-  tddService,
-  authService
+  tddService
 }) {
   return async function handleBaselineRoute(req, res, pathname) {
     // Accept a single screenshot as baseline
@@ -96,49 +94,16 @@ export function createBaselineRouter({
         return true;
       }
       try {
-        const body = await parseJsonBody(req);
-        const {
-          buildId,
-          organizationSlug,
-          projectSlug
+        let body = await parseJsonBody(req);
+        let {
+          buildId
         } = body;
         if (!buildId) {
           sendError(res, 400, 'buildId is required');
           return true;
         }
         output.info(`Downloading baselines from build ${buildId}...`);
-
-        // If organizationSlug and projectSlug are provided, use OAuth-based download
-        if (organizationSlug && projectSlug && authService) {
-          try {
-            const result = await tddService.downloadBaselinesWithAuth(buildId, organizationSlug, projectSlug, authService);
-            sendSuccess(res, {
-              success: true,
-              message: `Baselines downloaded from build ${buildId}`,
-              ...result
-            });
-            return true;
-          } catch (authError) {
-            // Log the OAuth error with details
-            output.warn(`OAuth download failed (org=${organizationSlug}, project=${projectSlug}): ${authError.message}`);
-
-            // If the error is a 404, it's likely the build doesn't belong to the project
-            // or the project/org is incorrect - provide a helpful error
-            if (authError.message?.includes('404')) {
-              sendError(res, 404, `Build not found or does not belong to project "${projectSlug}" in organization "${organizationSlug}". ` + `Please verify the build exists and you have access to it.`);
-              return true;
-            }
-
-            // For auth errors, try API token fallback
-            if (!authError.message?.includes('401')) {
-              // For other errors, don't fall through - report them directly
-              throw authError;
-            }
-          }
-        }
-
-        // Fall back to API token-based download (when no OAuth info or OAuth auth failed)
-        const result = await tddService.downloadBaselines('test',
+        let result = await tddService.downloadBaselines('test',
         // environment
         null,
         // branch (not needed when buildId is specified)

package/dist/services/api-service.js

@@ -122,6 +122,16 @@ export class ApiService {
     return this.request(endpoint);
   }
 
+  /**
+   * Get TDD baselines for a build
+   * Returns screenshots with pre-computed filenames for baseline download
+   * @param {string} buildId - Build ID
+   * @returns {Promise<Object>} { build, screenshots, signatureProperties }
+   */
+  async getTddBaselines(buildId) {
+    return this.request(`/api/sdk/builds/${buildId}/tdd-baselines`);
+  }
+
   /**
    * Get comparison information
    * @param {string} comparisonId - Comparison ID

package/dist/services/tdd-service.js

@@ -21,7 +21,7 @@
  */
 
 import crypto from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { compare } from '@vizzly-testing/honeydiff';
 import { NetworkError } from '../errors/vizzly-error.js';
@@ -178,41 +178,71 @@ export class TddService {
     try {
       let baselineBuild;
       if (buildId) {
-        // Use specific build ID - get it with screenshots in one call
-        const apiResponse = await this.api.getBuild(buildId, 'screenshots');
-
-        // API response available in verbose mode
-        output.debug('tdd', 'fetched baseline build', {
-          id: apiResponse?.build?.id || apiResponse?.id
-        });
+        // Use the tdd-baselines endpoint which returns pre-computed filenames
+        let apiResponse = await this.api.getTddBaselines(buildId);
         if (!apiResponse) {
           throw new Error(`Build ${buildId} not found or API returned null`);
         }
 
+        // When downloading baselines, always start with a clean slate
+        // This handles signature property changes, build switches, and any stale state
+        output.info('Clearing local state before downloading baselines...');
+        try {
+          // Clear everything - baselines, current screenshots, diffs, and metadata
+          // This ensures we start fresh with the new baseline build
+          rmSync(this.baselinePath, {
+            recursive: true,
+            force: true
+          });
+          rmSync(this.currentPath, {
+            recursive: true,
+            force: true
+          });
+          rmSync(this.diffPath, {
+            recursive: true,
+            force: true
+          });
+          mkdirSync(this.baselinePath, {
+            recursive: true
+          });
+          mkdirSync(this.currentPath, {
+            recursive: true
+          });
+          mkdirSync(this.diffPath, {
+            recursive: true
+          });
+
+          // Clear baseline metadata file (will be regenerated with new baseline)
+          const baselineMetadataPath = safePath(this.workingDir, '.vizzly', 'baseline-metadata.json');
+          if (existsSync(baselineMetadataPath)) {
+            rmSync(baselineMetadataPath, {
+              force: true
+            });
+          }
+        } catch (error) {
+          output.error(`Failed to clear local state: ${error.message}`);
+        }
+
         // Extract signature properties from API response (for variant support)
         if (apiResponse.signatureProperties && Array.isArray(apiResponse.signatureProperties)) {
           this.signatureProperties = apiResponse.signatureProperties;
           if (this.signatureProperties.length > 0) {
-            output.info(`Using custom signature properties: ${this.signatureProperties.join(', ')}`);
+            output.info(`Using signature properties: ${this.signatureProperties.join(', ')}`);
           }
         }
-
-        // Handle wrapped response format
-        baselineBuild = apiResponse.build || apiResponse;
-        if (!baselineBuild.id) {
-          output.warn(`⚠️  Build response structure: ${JSON.stringify(Object.keys(apiResponse))}`);
-          output.warn(`⚠️  Extracted build keys: ${JSON.stringify(Object.keys(baselineBuild))}`);
-        }
+        baselineBuild = apiResponse.build;
 
         // Check build status and warn if it's not successful
         if (baselineBuild.status === 'failed') {
           output.warn(`⚠️  Build ${buildId} is marked as FAILED - falling back to local baselines`);
           output.info(`💡 To use remote baselines, specify a successful build ID instead`);
-          // Fall back to local baseline logic
           return await this.handleLocalBaselines();
         } else if (baselineBuild.status !== 'completed') {
           output.warn(`⚠️  Build ${buildId} has status: ${baselineBuild.status} (expected: completed)`);
         }
+
+        // Attach screenshots to build for unified processing below
+        baselineBuild.screenshots = apiResponse.screenshots;
       } else if (comparisonId) {
         // Use specific comparison ID - download only this comparison's baseline screenshot
         output.info(`Using comparison: ${comparisonId}`);
@@ -262,6 +292,11 @@ export class TddService {
         }
         output.info(`📊 Extracted properties for signature: ${JSON.stringify(screenshotProperties)}`);
 
+        // Generate filename locally for comparison path (we don't have API-provided filename)
+        const screenshotName = comparison.baseline_name || comparison.current_name;
+        const signature = generateScreenshotSignature(screenshotName, screenshotProperties, this.signatureProperties);
+        const filename = generateBaselineFilename(screenshotName, signature);
+
         // For a specific comparison, we only download that one baseline screenshot
         // Create a mock build structure with just this one screenshot
         baselineBuild = {
@@ -269,10 +304,11 @@ export class TddService {
           name: `Comparison ${comparisonId.substring(0, 8)}`,
           screenshots: [{
             id: comparison.baseline_screenshot.id,
-            name: comparison.baseline_name || comparison.current_name,
+            name: screenshotName,
             original_url: baselineUrl,
             metadata: screenshotProperties,
-            properties: screenshotProperties
+            properties: screenshotProperties,
+            filename: filename // Generated locally for comparison path
           }]
         };
       } else {
@@ -288,18 +324,27 @@ export class TddService {
           output.info('💡 Run a build in normal mode first to create baselines');
           return null;
         }
-        baselineBuild = builds.data[0];
+
+        // Use getTddBaselines to get screenshots with pre-computed filenames
+        const apiResponse = await this.api.getTddBaselines(builds.data[0].id);
+        if (!apiResponse) {
+          throw new Error(`Build ${builds.data[0].id} not found or API returned null`);
+        }
+
+        // Extract signature properties from API response (for variant support)
+        if (apiResponse.signatureProperties && Array.isArray(apiResponse.signatureProperties)) {
+          this.signatureProperties = apiResponse.signatureProperties;
+          if (this.signatureProperties.length > 0) {
+            output.info(`Using custom signature properties: ${this.signatureProperties.join(', ')}`);
+          }
+        }
+        baselineBuild = apiResponse.build;
+        baselineBuild.screenshots = apiResponse.screenshots;
       }
 
-      // For specific buildId, we already have screenshots
+      // For both buildId and getBuilds paths, we now have screenshots with filenames
       // For comparisonId, we created a mock build with just the one screenshot
-      // Otherwise, get build details with screenshots
       let buildDetails = baselineBuild;
-      if (!buildId && !comparisonId) {
-        // Get build details with screenshots for non-buildId/non-comparisonId cases
-        const actualBuildId = baselineBuild.id;
-        buildDetails = await this.api.getBuild(actualBuildId, 'screenshots');
-      }
       if (!buildDetails.screenshots || buildDetails.screenshots.length === 0) {
         output.warn('⚠️  No screenshots found in baseline build');
         return null;
@@ -308,12 +353,12 @@ export class TddService {
       output.info(`Checking ${colors.cyan(buildDetails.screenshots.length)} baseline screenshots...`);
 
       // Check existing baseline metadata for efficient SHA comparison
-      const existingBaseline = await this.loadBaseline();
-      const existingShaMap = new Map();
+      let existingBaseline = await this.loadBaseline();
+      let existingShaMap = new Map();
       if (existingBaseline) {
         existingBaseline.screenshots.forEach(s => {
-          if (s.sha256 && s.signature) {
-            existingShaMap.set(s.signature, s.sha256);
+          if (s.sha256 && s.filename) {
+            existingShaMap.set(s.filename, s.sha256);
           }
         });
       }
@@ -338,26 +383,21 @@ export class TddService {
           continue;
         }
 
-        // Generate signature for baseline matching (same as compareScreenshot)
-        // Build properties object with top-level viewport_width and browser
-        // These are returned as top-level fields from the API, not inside metadata
-        const properties = validateScreenshotProperties({
-          viewport_width: screenshot.viewport_width,
-          browser: screenshot.browser,
-          ...(screenshot.metadata || screenshot.properties || {})
-        });
-        const signature = generateScreenshotSignature(sanitizedName, properties, this.signatureProperties);
-
-        // Use API-provided filename if available, otherwise generate hash-based filename
-        // Both return the full filename with .png extension
-        const filename = screenshot.filename || generateBaselineFilename(sanitizedName, signature);
-        const imagePath = safePath(this.baselinePath, filename);
+        // Use API-provided filename (required from tdd-baselines endpoint)
+        // This ensures filenames match between cloud and local TDD
+        let filename = screenshot.filename;
+        if (!filename) {
+          output.warn(`⚠️  Screenshot ${sanitizedName} has no filename from API - skipping`);
+          errorCount++;
+          continue;
+        }
+        let imagePath = safePath(this.baselinePath, filename);
 
-        // Check if we already have this file with the same SHA (using metadata)
+        // Check if we already have this file with the same SHA
         if (existsSync(imagePath) && screenshot.sha256) {
-          const storedSha = existingShaMap.get(signature);
+          let storedSha = existingShaMap.get(filename);
           if (storedSha === screenshot.sha256) {
-            downloadedCount++; // Count as "downloaded" since we have it
+            downloadedCount++;
             skippedCount++;
             continue;
           }
@@ -375,9 +415,7 @@ export class TddService {
           sanitizedName,
           imagePath,
           downloadUrl,
-          signature,
-          filename,
-          properties
+          filename
         });
       }
 
@@ -458,41 +496,23 @@ export class TddService {
           approvalStatus: baselineBuild.approval_status,
           completedAt: baselineBuild.completed_at
         },
-        screenshots: buildDetails.screenshots.map(s => {
-          let sanitizedName;
-          try {
-            sanitizedName = sanitizeScreenshotName(s.name);
-          } catch (error) {
-            output.warn(`Screenshot name sanitization failed for '${s.name}': ${error.message}`);
-            return null; // Skip invalid screenshots
+        screenshots: buildDetails.screenshots.filter(s => s.filename) // Only include screenshots with filenames
+        .map(s => ({
+          name: sanitizeScreenshotName(s.name),
+          originalName: s.name,
+          sha256: s.sha256,
+          id: s.id,
+          filename: s.filename,
+          path: safePath(this.baselinePath, s.filename),
+          browser: s.browser,
+          viewport_width: s.viewport_width,
+          originalUrl: s.original_url,
+          fileSize: s.file_size_bytes,
+          dimensions: {
+            width: s.width,
+            height: s.height
           }
-
-          // Build properties object with top-level viewport_width and browser
-          // These are returned as top-level fields from the API, not inside metadata
-          const properties = validateScreenshotProperties({
-            viewport_width: s.viewport_width,
-            browser: s.browser,
-            ...(s.metadata || s.properties || {})
-          });
-          const signature = generateScreenshotSignature(sanitizedName, properties, this.signatureProperties);
-          const filename = generateBaselineFilename(sanitizedName, signature);
-          return {
-            name: sanitizedName,
-            originalName: s.name,
-            sha256: s.sha256,
-            // Store remote SHA for quick comparison
-            id: s.id,
-            properties: properties,
-            path: safePath(this.baselinePath, filename),
-            signature: signature,
-            originalUrl: s.original_url,
-            fileSize: s.file_size_bytes,
-            dimensions: {
-              width: s.width,
-              height: s.height
-            }
-          };
-        }).filter(Boolean) // Remove null entries from invalid screenshots
+        }))
       };
       const metadataPath = join(this.baselinePath, 'metadata.json');
       writeFileSync(metadataPath, JSON.stringify(this.baselineData, null, 2));
@@ -685,180 +705,6 @@ export class TddService {
     };
   }
 
-  /**
-   * Download baselines using OAuth authentication
-   * Used when user is logged in via device flow but no API token is configured
-   * @param {string} buildId - Build ID to download from
-   * @param {string} organizationSlug - Organization slug
-   * @param {string} projectSlug - Project slug
-   * @param {Object} authService - Auth service for OAuth requests
-   * @returns {Promise<Object>} Download result
-   */
-  async downloadBaselinesWithAuth(buildId, organizationSlug, projectSlug, authService) {
-    output.info(`Downloading baselines using OAuth from build ${buildId}...`);
-    try {
-      // Fetch build with screenshots via OAuth endpoint
-      const endpoint = `/api/build/${projectSlug}/${buildId}/tdd-baselines`;
-      const response = await authService.authenticatedRequest(endpoint, {
-        method: 'GET',
-        headers: {
-          'X-Organization': organizationSlug
-        }
-      });
-      const {
-        build,
-        screenshots,
-        signatureProperties
-      } = response;
-
-      // Extract signature properties from API response (for variant support)
-      if (signatureProperties && Array.isArray(signatureProperties)) {
-        this.signatureProperties = signatureProperties;
-        if (this.signatureProperties.length > 0) {
-          output.info(`Using custom signature properties: ${this.signatureProperties.join(', ')}`);
-        }
-      }
-      if (!screenshots || screenshots.length === 0) {
-        output.warn('⚠️  No screenshots found in build');
-        return {
-          downloadedCount: 0,
-          skippedCount: 0,
-          errorCount: 0
-        };
-      }
-      output.info(`Using baseline from build: ${colors.cyan(build.name || 'Unknown')} (${build.id})`);
-      output.info(`Checking ${colors.cyan(screenshots.length)} baseline screenshots...`);
-
-      // Load existing baseline metadata for SHA comparison
-      const existingBaseline = await this.loadBaseline();
-      const existingShaMap = new Map();
-      if (existingBaseline) {
-        existingBaseline.screenshots.forEach(s => {
-          if (s.sha256 && s.signature) {
-            existingShaMap.set(s.signature, s.sha256);
-          }
-        });
-      }
-
-      // Process and download screenshots
-      let downloadedCount = 0;
-      let skippedCount = 0;
-      let errorCount = 0;
-      const downloadedScreenshots = [];
-      for (const screenshot of screenshots) {
-        let sanitizedName;
-        try {
-          sanitizedName = sanitizeScreenshotName(screenshot.name);
-        } catch (error) {
-          output.warn(`Screenshot name sanitization failed for '${screenshot.name}': ${error.message}`);
-          errorCount++;
-          continue;
-        }
-
-        // Build properties object with top-level viewport_width and browser
-        // These are returned as top-level fields from the API, not inside metadata
-        const properties = validateScreenshotProperties({
-          viewport_width: screenshot.viewport_width,
-          browser: screenshot.browser,
-          ...screenshot.metadata
-        });
-        const signature = generateScreenshotSignature(sanitizedName, properties, this.signatureProperties);
-        // Use API-provided filename if available, otherwise generate hash-based filename
-        const filename = screenshot.filename || generateBaselineFilename(sanitizedName, signature);
-        const filePath = safePath(this.baselinePath, filename);
-
-        // Check if we can skip via SHA comparison
-        if (screenshot.sha256 && existingShaMap.get(signature) === screenshot.sha256) {
-          skippedCount++;
-          downloadedScreenshots.push({
-            name: sanitizedName,
-            sha256: screenshot.sha256,
-            signature,
-            path: filePath,
-            properties
-          });
-          continue;
-        }
-
-        // Download the screenshot
-        const downloadUrl = screenshot.original_url;
-        if (!downloadUrl) {
-          output.warn(`⚠️  No download URL for screenshot: ${sanitizedName}`);
-          errorCount++;
-          continue;
-        }
-        try {
-          const imageResponse = await fetchWithTimeout(downloadUrl, {}, 30000);
-          if (!imageResponse.ok) {
-            throw new Error(`HTTP ${imageResponse.status}`);
-          }
-          const imageBuffer = Buffer.from(await imageResponse.arrayBuffer());
-
-          // Calculate SHA256 of downloaded content
-          const sha256 = crypto.createHash('sha256').update(imageBuffer).digest('hex');
-          writeFileSync(filePath, imageBuffer);
-          downloadedCount++;
-          downloadedScreenshots.push({
-            name: sanitizedName,
-            sha256,
-            signature,
-            path: filePath,
-            properties,
-            originalUrl: downloadUrl
-          });
-        } catch (error) {
-          output.warn(`⚠️  Failed to download ${sanitizedName}: ${error.message}`);
-          errorCount++;
-        }
-      }
-
-      // Store baseline metadata
-      this.baselineData = {
-        buildId: build.id,
-        buildName: build.name,
-        branch: build.branch,
-        threshold: this.threshold,
-        signatureProperties: this.signatureProperties,
-        // Store for TDD comparison
-        screenshots: downloadedScreenshots
-      };
-      const metadataPath = join(this.baselinePath, 'metadata.json');
-      writeFileSync(metadataPath, JSON.stringify(this.baselineData, null, 2));
-
-      // Save baseline build metadata
-      const baselineMetadataPath = safePath(this.workingDir, '.vizzly', 'baseline-metadata.json');
-      writeFileSync(baselineMetadataPath, JSON.stringify({
-        buildId: build.id,
-        buildName: build.name,
-        branch: build.branch,
-        commitSha: build.commit_sha,
-        downloadedAt: new Date().toISOString()
-      }, null, 2));
-
-      // Summary
-      if (skippedCount > 0 && downloadedCount === 0) {
-        output.info(`✅ All ${skippedCount} baselines up-to-date (matching local SHA)`);
-      } else if (skippedCount > 0) {
-        output.info(`✅ Downloaded ${downloadedCount} new screenshots, ${skippedCount} already up-to-date`);
-      } else {
-        output.info(`✅ Downloaded ${downloadedCount}/${screenshots.length} screenshots successfully`);
-      }
-      if (errorCount > 0) {
-        output.warn(`⚠️  ${errorCount} screenshots failed to download`);
-      }
-      return {
-        downloadedCount,
-        skippedCount,
-        errorCount,
-        buildId: build.id,
-        buildName: build.name
-      };
-    } catch (error) {
-      output.error(`❌ OAuth download failed: ${error.message} (org=${organizationSlug}, project=${projectSlug}, build=${buildId})`);
-      throw error;
-    }
-  }
-
   /**
    * Handle local baseline logic (either load existing or prepare for new baselines)
    * @returns {Promise<Object|null>} Baseline data or null if no local baselines exist

package/dist/utils/security.js

@@ -13,6 +13,62 @@ import * as output from './output.js';
  * @param {boolean} allowSlashes - Whether to allow forward slashes (for browser version strings)
  * @returns {string} Sanitized screenshot name
  */
+/**
+ * Validate screenshot name for security (no transformations, just validation)
+ * Throws if name contains path traversal or other dangerous patterns
+ *
+ * @param {string} name - Screenshot name to validate
+ * @param {number} maxLength - Maximum allowed length
+ * @returns {string} The original name (unchanged) if valid
+ * @throws {Error} If name contains dangerous patterns
+ */
+export function validateScreenshotName(name, maxLength = 255) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('Screenshot name must be a non-empty string');
+  }
+  if (name.length > maxLength) {
+    throw new Error(`Screenshot name exceeds maximum length of ${maxLength} characters`);
+  }
+
+  // Block directory traversal patterns
+  if (name.includes('..') || name.includes('\\')) {
+    throw new Error('Screenshot name contains invalid path characters');
+  }
+
+  // Block forward slashes (path separators)
+  if (name.includes('/')) {
+    throw new Error('Screenshot name cannot contain forward slashes');
+  }
+
+  // Block absolute paths
+  if (isAbsolute(name)) {
+    throw new Error('Screenshot name cannot be an absolute path');
+  }
+
+  // Return the original name unchanged - validation only!
+  return name;
+}
+
+/**
+ * Validate screenshot name for security (allows spaces, preserves original name)
+ *
+ * This function only validates for security - it does NOT transform spaces.
+ * Spaces are preserved so that:
+ * 1. generateScreenshotSignature() uses the original name with spaces (matches cloud)
+ * 2. generateBaselineFilename() handles space→hyphen conversion (matches cloud)
+ *
+ * Flow: "VBtn dark" → sanitize → "VBtn dark" → signature: "VBtn dark|1265||" → filename: "VBtn-dark_hash.png"
+ *
+ * @param {string} name - Screenshot name to validate
+ * @param {number} maxLength - Maximum allowed length (default: 255)
+ * @param {boolean} allowSlashes - Whether to allow forward slashes (for browser version strings)
+ * @returns {string} The validated name (unchanged if valid, spaces preserved)
+ * @throws {Error} If name contains dangerous patterns
+ *
+ * @example
+ * sanitizeScreenshotName("VBtn dark") // Returns "VBtn dark" (spaces preserved)
+ * sanitizeScreenshotName("My/Component") // Throws error (contains /)
+ */
 export function sanitizeScreenshotName(name, maxLength = 255, allowSlashes = false) {
   if (typeof name !== 'string' || name.length === 0) {
     throw new Error('Screenshot name must be a non-empty string');
@@ -36,9 +92,10 @@ export function sanitizeScreenshotName(name, maxLength = 255, allowSlashes = fal
     throw new Error('Screenshot name cannot be an absolute path');
   }
 
-  // Allow only safe characters: alphanumeric, hyphens, underscores, dots, and optionally slashes
+  // Allow only safe characters: alphanumeric, hyphens, underscores, dots, spaces, and optionally slashes
+  // Spaces are allowed here and will be converted to hyphens in generateBaselineFilename() to match cloud behavior
   // Replace other characters with underscores
-  const allowedChars = allowSlashes ? /[^a-zA-Z0-9._/-]/g : /[^a-zA-Z0-9._-]/g;
+  const allowedChars = allowSlashes ? /[^a-zA-Z0-9._ /-]/g : /[^a-zA-Z0-9._ -]/g;
   let sanitized = name.replace(allowedChars, '_');
 
   // Prevent names that start with dots (hidden files)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",