@vizzly-testing/cli 0.18.0 → 0.19.0

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/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`;
 }
 
 /**
@@ -322,8 +347,11 @@ export class TddService {
           ...(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 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);
 
         // Check if we already have this file with the same SHA (using metadata)
         if (existsSync(imagePath) && screenshot.sha256) {
@@ -447,7 +475,7 @@ export class TddService {
             ...(s.metadata || s.properties || {})
           });
           const signature = generateScreenshotSignature(sanitizedName, properties, this.signatureProperties);
-          const filename = signatureToFilename(signature);
+          const filename = generateBaselineFilename(sanitizedName, signature);
           return {
             name: sanitizedName,
             originalName: s.name,
@@ -455,7 +483,7 @@ export class TddService {
             // Store remote SHA for quick comparison
             id: s.id,
             properties: properties,
-            path: safePath(this.baselinePath, `${filename}.png`),
+            path: safePath(this.baselinePath, filename),
             signature: signature,
             originalUrl: s.original_url,
             fileSize: s.file_size_bytes,
@@ -735,8 +763,9 @@ export class TddService {
           ...screenshot.metadata
         });
         const signature = generateScreenshotSignature(sanitizedName, properties, this.signatureProperties);
-        const filename = signatureToFilename(signature);
-        const filePath = safePath(this.baselinePath, `${filename}.png`);
+        // 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) {
@@ -900,6 +929,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 +943,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 +1339,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 +1515,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.0",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",