@vizzly-testing/cli 0.18.0 → 0.19.1

package/dist/cli.js

@@ -14,6 +14,7 @@ import { runDaemonChild, tddStartCommand, tddStatusCommand, tddStopCommand } fro
 import { uploadCommand, validateUploadOptions } from './commands/upload.js';
 import { validateWhoamiOptions, whoamiCommand } from './commands/whoami.js';
 import { loadPlugins } from './plugin-loader.js';
+import { createPluginServices } from './plugin-api.js';
 import { createServices } from './services/index.js';
 import { loadConfig } from './utils/config-loader.js';
 import * as output from './utils/output.js';
@@ -47,6 +48,7 @@ output.configure({
 });
 const config = await loadConfig(configPath, {});
 const services = createServices(config);
+const pluginServices = createPluginServices(services);
 let plugins = [];
 try {
   plugins = await loadPlugins(configPath, config);
@@ -55,7 +57,7 @@ try {
       // Add timeout protection for plugin registration (5 seconds)
       const registerPromise = plugin.register(program, {
         config,
-        services,
+        services: pluginServices,
         output,
         // Backwards compatibility alias for plugins using old API
         logger: output

package/dist/plugin-api.js

@@ -0,0 +1,43 @@
+/**
+ * Plugin API - Stable interface for Vizzly plugins
+ *
+ * This module defines the stable API contract for plugins. Only methods
+ * exposed here are considered part of the public API and are guaranteed
+ * to not break between minor versions.
+ *
+ * Internal services (apiService, uploader, buildManager, etc.) are NOT
+ * exposed to plugins to prevent coupling to implementation details.
+ */
+
+/**
+ * Creates a stable plugin services object from the internal services
+ *
+ * Only exposes:
+ * - testRunner: Build lifecycle management (createBuild, finalizeBuild, events)
+ * - serverManager: Screenshot server control (start, stop)
+ *
+ * @param {Object} services - Internal services from createServices()
+ * @returns {Object} Frozen plugin services object
+ */
+export function createPluginServices(services) {
+  let {
+    testRunner,
+    serverManager
+  } = services;
+  return Object.freeze({
+    testRunner: Object.freeze({
+      // EventEmitter methods for build lifecycle events
+      once: testRunner.once.bind(testRunner),
+      on: testRunner.on.bind(testRunner),
+      off: testRunner.off.bind(testRunner),
+      // Build lifecycle
+      createBuild: testRunner.createBuild.bind(testRunner),
+      finalizeBuild: testRunner.finalizeBuild.bind(testRunner)
+    }),
+    serverManager: Object.freeze({
+      // Server lifecycle
+      start: serverManager.start.bind(serverManager),
+      stop: serverManager.stop.bind(serverManager)
+    })
+  });
+}

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

@@ -245,17 +245,18 @@ export const createTddHandler = (config, workingDir, baselineBuild, baselineComp
       };
     }
 
-    // Extract viewport/browser to top-level properties (matching cloud API behavior)
-    // This ensures signature generation works correctly with: name|viewport_width|browser
+    // Extract ALL properties to top-level (matching cloud API behavior)
+    // This ensures signature generation works correctly for custom properties like theme, device, etc.
+    // Spread all validated properties first, then normalize viewport/browser for cloud format
     const extractedProperties = {
-      viewport_width: validatedProperties.viewport?.width || null,
-      viewport_height: validatedProperties.viewport?.height || null,
-      browser: validatedProperties.browser || null,
-      device: validatedProperties.device || null,
-      url: validatedProperties.url || null,
-      selector: validatedProperties.selector || null,
-      threshold: validatedProperties.threshold,
-      // Preserve full nested structure in metadata for compatibility
+      ...validatedProperties,
+      // Normalize viewport to top-level viewport_width/height (cloud format)
+      // Use nullish coalescing to preserve any existing top-level values
+      viewport_width: validatedProperties.viewport?.width ?? validatedProperties.viewport_width ?? null,
+      viewport_height: validatedProperties.viewport?.height ?? validatedProperties.viewport_height ?? null,
+      browser: validatedProperties.browser ?? null,
+      // Preserve nested structure in metadata for backward compatibility
+      // Signature generation checks multiple locations: top-level, metadata.*, metadata.properties.*
       metadata: validatedProperties
     };
 

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

@@ -1,3 +1,25 @@
+/**
+ * TDD Service - Local Visual Testing
+ *
+ * ⚠️  CRITICAL: Signature/filename generation MUST stay in sync with the cloud!
+ *
+ * Cloud counterpart: vizzly/src/utils/screenshot-identity.js
+ *   - generateScreenshotSignature()
+ *   - generateBaselineFilename()
+ *
+ * Contract tests: Both repos have golden tests that must produce identical values:
+ *   - Cloud: tests/contracts/signature-parity.test.js
+ *   - CLI:   tests/contracts/signature-parity.spec.js
+ *
+ * If you modify signature or filename generation here, you MUST:
+ *   1. Make the same change in the cloud repo
+ *   2. Update golden test values in BOTH repos
+ *   3. Run contract tests in both repos to verify parity
+ *
+ * The signature format is: name|viewport_width|browser|custom1|custom2|...
+ * The filename format is: {sanitized-name}_{12-char-sha256-hash}.png
+ */
+
 import crypto from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -13,13 +35,10 @@ import { HtmlReportGenerator } from './html-report-generator.js';
 
 /**
  * Generate a screenshot signature for baseline matching
- * Uses same logic as screenshot-identity.js: name + viewport_width + browser + custom properties
  *
- * Matches backend signature generation which uses:
- * - screenshot.name
- * - screenshot.viewport_width (top-level property)
- * - screenshot.browser (top-level property)
- * - custom properties from project's baseline_signature_properties setting
+ * ⚠️  SYNC WITH: vizzly/src/utils/screenshot-identity.js - generateScreenshotSignature()
+ *
+ * Uses same logic as cloud: name + viewport_width + browser + custom properties
  *
  * @param {string} name - Screenshot name
  * @param {Object} properties - Screenshot properties (viewport, browser, metadata, etc.)
@@ -62,17 +81,23 @@ function generateScreenshotSignature(name, properties = {}, customProperties = [
 }
 
 /**
- * Create a safe filename from signature
- * Handles custom property values that may contain spaces or special characters
+ * Generate a stable, filesystem-safe filename for a screenshot baseline
+ * Uses a hash of the signature to avoid character encoding issues
+ * Matches the cloud's generateBaselineFilename implementation exactly
  *
- * IMPORTANT: Does NOT collapse multiple underscores because empty signature
- * positions (e.g., null browser) result in `||` which becomes `__` and must
- * be preserved for cloud compatibility.
+ * @param {string} name - Screenshot name
+ * @param {string} signature - Full signature string
+ * @returns {string} Filename like "homepage_a1b2c3d4e5f6.png"
  */
-function signatureToFilename(signature) {
-  return signature.replace(/\|/g, '_') // pipes to underscores
-  .replace(/\s+/g, '-') // spaces to hyphens (not underscores, to distinguish from position separators)
-  .replace(/[/\\:*?"<>]/g, ''); // remove unsafe filesystem chars
+function generateBaselineFilename(name, signature) {
+  const hash = crypto.createHash('sha256').update(signature).digest('hex').slice(0, 12);
+
+  // Sanitize the name for filesystem safety
+  const safeName = name.replace(/[/\\:*?"<>|]/g, '') // Remove unsafe chars
+  .replace(/\s+/g, '-') // Spaces to hyphens
+  .slice(0, 50); // Limit length
+
+  return `${safeName}_${hash}.png`;
 }
 
 /**
@@ -153,13 +178,8 @@ 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`);
         }
@@ -171,23 +191,19 @@ export class TddService {
             output.info(`Using custom 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}`);
@@ -237,6 +253,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 = {
@@ -244,10 +265,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 {
@@ -263,18 +285,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;
@@ -283,12 +314,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);
           }
         });
       }
@@ -313,23 +344,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);
-        const filename = signatureToFilename(signature);
-        const imagePath = safePath(this.baselinePath, `${filename}.png`);
+        // 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;
           }
@@ -347,9 +376,7 @@ export class TddService {
           sanitizedName,
           imagePath,
           downloadUrl,
-          signature,
-          filename,
-          properties
+          filename
         });
       }
 
@@ -430,41 +457,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 = signatureToFilename(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}.png`),
-            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));
@@ -657,179 +666,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);
-        const filename = signatureToFilename(signature);
-        const filePath = safePath(this.baselinePath, `${filename}.png`);
-
-        // 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
@@ -900,6 +736,12 @@ export class TddService {
       validatedProperties = {};
     }
 
+    // Preserve metadata object through validation (validateScreenshotProperties strips non-primitives)
+    // This is needed because signature generation checks properties.metadata.* for custom properties
+    if (properties.metadata && typeof properties.metadata === 'object') {
+      validatedProperties.metadata = properties.metadata;
+    }
+
     // Normalize properties to match backend format (viewport_width at top level)
     // This ensures signature generation matches backend's screenshot-identity.js
     if (validatedProperties.viewport?.width && !validatedProperties.viewport_width) {
@@ -908,10 +750,11 @@ export class TddService {
 
     // Generate signature for baseline matching (name + viewport_width + browser + custom props)
     const signature = generateScreenshotSignature(sanitizedName, validatedProperties, this.signatureProperties);
-    const filename = signatureToFilename(signature);
-    const currentImagePath = safePath(this.currentPath, `${filename}.png`);
-    const baselineImagePath = safePath(this.baselinePath, `${filename}.png`);
-    const diffImagePath = safePath(this.diffPath, `${filename}.png`);
+    // Use hash-based filename for reliable matching (matches cloud format)
+    const filename = generateBaselineFilename(sanitizedName, signature);
+    const currentImagePath = safePath(this.currentPath, filename);
+    const baselineImagePath = safePath(this.baselinePath, filename);
+    const diffImagePath = safePath(this.diffPath, filename);
 
     // Save current screenshot
     writeFileSync(currentImagePath, imageBuffer);
@@ -1303,8 +1146,8 @@ export class TddService {
       }
       const validatedProperties = validateScreenshotProperties(comparison.properties || {});
       const signature = generateScreenshotSignature(sanitizedName, validatedProperties, this.signatureProperties);
-      const filename = signatureToFilename(signature);
-      const baselineImagePath = safePath(this.baselinePath, `${filename}.png`);
+      const filename = generateBaselineFilename(sanitizedName, signature);
+      const baselineImagePath = safePath(this.baselinePath, filename);
       try {
         // Copy current screenshot to baseline
         const currentBuffer = readFileSync(current);
@@ -1479,10 +1322,10 @@ export class TddService {
     const sanitizedName = comparison.name;
     const properties = comparison.properties || {};
     const signature = generateScreenshotSignature(sanitizedName, properties, this.signatureProperties);
-    const filename = signatureToFilename(signature);
+    const filename = generateBaselineFilename(sanitizedName, signature);
 
     // Find the current screenshot file
-    const currentImagePath = safePath(this.currentPath, `${filename}.png`);
+    const currentImagePath = safePath(this.currentPath, filename);
     if (!existsSync(currentImagePath)) {
       output.error(`Current screenshot not found at: ${currentImagePath}`);
       throw new Error(`Current screenshot not found: ${sanitizedName} (looked at ${currentImagePath})`);

package/dist/types/index.d.ts

@@ -351,6 +351,90 @@ export interface Services {
   testRunner: unknown;
 }
 
+// ============================================================================
+// Plugin API Types (Stable Contract)
+// ============================================================================
+
+/**
+ * Stable TestRunner interface for plugins.
+ * Only these methods are guaranteed to remain stable across minor versions.
+ */
+export interface PluginTestRunner {
+  /** Listen for a single event emission */
+  once(event: string, callback: (...args: unknown[]) => void): void;
+  /** Subscribe to events */
+  on(event: string, callback: (...args: unknown[]) => void): void;
+  /** Unsubscribe from events */
+  off(event: string, callback: (...args: unknown[]) => void): void;
+  /** Create a new build and return the build ID */
+  createBuild(options: BuildOptions, isTddMode: boolean): Promise<string>;
+  /** Finalize a build after all screenshots are captured */
+  finalizeBuild(
+    buildId: string,
+    isTddMode: boolean,
+    success: boolean,
+    executionTime: number
+  ): Promise<void>;
+}
+
+/**
+ * Stable ServerManager interface for plugins.
+ * Only these methods are guaranteed to remain stable across minor versions.
+ */
+export interface PluginServerManager {
+  /** Start the screenshot server */
+  start(buildId: string, tddMode: boolean, setBaseline: boolean): Promise<void>;
+  /** Stop the screenshot server */
+  stop(): Promise<void>;
+}
+
+/**
+ * Stable services interface for plugins.
+ * This is the public API contract - internal services are NOT exposed.
+ */
+export interface PluginServices {
+  testRunner: PluginTestRunner;
+  serverManager: PluginServerManager;
+}
+
+/**
+ * Build options for createBuild()
+ */
+export interface BuildOptions {
+  port?: number;
+  timeout?: number;
+  buildName?: string;
+  branch?: string;
+  commit?: string;
+  message?: string;
+  environment?: string;
+  threshold?: number;
+  eager?: boolean;
+  allowNoToken?: boolean;
+  wait?: boolean;
+  uploadAll?: boolean;
+  pullRequestNumber?: string;
+  parallelId?: string;
+}
+
+/**
+ * Context object passed to plugin register() function.
+ * This is the stable plugin API contract.
+ */
+export interface PluginContext {
+  /** Merged Vizzly configuration */
+  config: VizzlyConfig;
+  /** Stable services for plugins */
+  services: PluginServices;
+  /** Output utilities for logging */
+  output: OutputUtils;
+  /** @deprecated Use output instead. Alias for backwards compatibility. */
+  logger: OutputUtils;
+}
+
+/** Create stable plugin services from internal services */
+export function createPluginServices(services: Services): PluginServices;
+
 // ============================================================================
 // Output Utilities
 // ============================================================================

package/docs/plugins.md

@@ -104,8 +104,8 @@ export default {
       .action(async (arg, options) => {
         output.info(`Running my-command with ${arg}`);
 
-        // Access shared services if needed
-        let apiService = await services.get('apiService');
+        // Access shared services directly
+        let apiService = services.apiService;
 
         // Your command logic here
       });
@@ -134,26 +134,55 @@ The `register` function receives two arguments:
    - `output` - Unified output module with `.debug()`, `.info()`, `.warn()`, `.error()`, `.success()` methods
    - `services` - Service container with access to internal Vizzly services
 
-### Available Services
+### Available Services (Stable API)
 
-Plugins can access these services from the container:
+The `services` object provides a stable API for plugins. Only these services and methods are
+guaranteed to remain stable across minor versions:
 
-- **`apiService`** - Vizzly API client for interacting with the platform
-- **`uploader`** - Screenshot upload service
-- **`buildManager`** - Build lifecycle management
-- **`serverManager`** - Screenshot server management
-- **`tddService`** - TDD mode services
-- **`testRunner`** - Test execution service
+#### `services.testRunner`
 
-Example accessing a service:
+Manages build lifecycle and emits events:
+
+- **`once(event, callback)`** - Listen for a single event emission
+- **`on(event, callback)`** - Subscribe to events
+- **`off(event, callback)`** - Unsubscribe from events
+- **`createBuild(options, isTddMode)`** - Create a new build, returns `Promise<buildId>`
+- **`finalizeBuild(buildId, isTddMode, success, executionTime)`** - Finalize a build
+
+Events emitted:
+- `build-created` - Emitted with `{ url }` when a build is created
+
+#### `services.serverManager`
+
+Controls the screenshot capture server:
+
+- **`start(buildId, tddMode, setBaseline)`** - Start the screenshot server
+- **`stop()`** - Stop the screenshot server
+
+Example accessing services:
 
 ```javascript
 register(program, { config, output, services }) {
   program
-    .command('upload-screenshots <dir>')
-    .action(async (dir) => {
-      let uploader = await services.get('uploader');
-      await uploader.uploadScreenshots(screenshots);
+    .command('capture')
+    .description('Capture screenshots with custom workflow')
+    .action(async () => {
+      let { testRunner, serverManager } = services;
+
+      // Listen for build creation
+      testRunner.once('build-created', ({ url }) => {
+        output.info(`Build created: ${url}`);
+      });
+
+      // Create build and start server
+      let buildId = await testRunner.createBuild({ buildName: 'Custom' }, false);
+      await serverManager.start(buildId, false, false);
+
+      // ... capture screenshots ...
+
+      // Finalize and cleanup
+      await testRunner.finalizeBuild(buildId, false, true, Date.now());
+      await serverManager.stop();
     });
 }
 ```
@@ -290,9 +319,9 @@ Use async/await for asynchronous operations:
 
 ```javascript
 .action(async (options) => {
-  let service = await services.get('apiService');
-  let result = await service.doSomething();
-  output.info(`Result: ${result}`);
+  let { testRunner } = services;
+  let buildId = await testRunner.createBuild({ buildName: 'Test' }, false);
+  output.info(`Created build: ${buildId}`);
 });
 ```
 
@@ -384,21 +413,27 @@ export default {
       .description('Capture screenshots from Storybook build')
       .option('--viewports <list>', 'Comma-separated viewports', '1280x720')
       .action(async (path, options) => {
+        let { testRunner, serverManager } = services;
+        let startTime = Date.now();
+
+        // Create build and start server
+        let buildId = await testRunner.createBuild({ buildName: 'Storybook' }, false);
+        await serverManager.start(buildId, false, false);
+
         output.info(`Crawling Storybook at ${path}`);
 
         // Import dependencies lazily
         let { crawlStorybook } = await import('./crawler.js');
 
-        // Capture screenshots
-        let screenshots = await crawlStorybook(path, {
+        // Capture screenshots (uses vizzlyScreenshot internally)
+        await crawlStorybook(path, {
           viewports: options.viewports.split(','),
         });
 
-        output.info(`Captured ${screenshots.length} screenshots`);
-
-        // Upload using Vizzly's uploader service
-        let uploader = await services.get('uploader');
-        await uploader.uploadScreenshots(screenshots);
+        // Finalize build
+        let executionTime = Date.now() - startTime;
+        await testRunner.finalizeBuild(buildId, false, true, executionTime);
+        await serverManager.stop();
 
         output.success('Upload complete!');
       });

package/package.json

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