@vizzly-testing/cli 0.9.1 → 0.10.1

package/dist/types/client/index.d.ts

@@ -6,7 +6,6 @@
  * @param {Object} [options] - Optional configuration
  * @param {Record<string, any>} [options.properties] - Additional properties to attach to the screenshot
  * @param {number} [options.threshold=0] - Pixel difference threshold (0-100)
- * @param {string} [options.variant] - Variant name for organizing screenshots
  * @param {boolean} [options.fullPage=false] - Whether this is a full page screenshot
  *
  * @returns {Promise<void>}
@@ -33,7 +32,6 @@
 export function vizzlyScreenshot(name: string, imageBuffer: Buffer, options?: {
     properties?: Record<string, any>;
     threshold?: number;
-    variant?: string;
     fullPage?: boolean;
 }): Promise<void>;
 /**

package/dist/types/commands/init.d.ts

@@ -5,10 +5,29 @@ export function init(options?: {}): Promise<void>;
  * Simple configuration setup for Vizzly CLI
  */
 export class InitCommand {
-    constructor(logger: any);
+    constructor(logger: any, plugins?: any[]);
     logger: any;
+    plugins: any[];
     run(options?: {}): Promise<void>;
     generateConfigFile(configPath: any): Promise<void>;
+    /**
+     * Generate configuration sections for plugins
+     * @returns {string} Plugin config sections as formatted string
+     */
+    generatePluginConfigs(): string;
+    /**
+     * Format a plugin's config schema as JavaScript code
+     * @param {Object} plugin - Plugin with configSchema
+     * @returns {string} Formatted config string
+     */
+    formatPluginConfig(plugin: any): string;
+    /**
+     * Format a JavaScript value with proper indentation
+     * @param {*} value - Value to format
+     * @param {number} depth - Current indentation depth
+     * @returns {string} Formatted value
+     */
+    formatValue(value: any, depth?: number): string;
     showNextSteps(): void;
     fileExists(filePath: any): Promise<boolean>;
 }

package/dist/types/plugin-loader.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Load and register plugins from node_modules and config
+ * @param {string|null} configPath - Path to config file
+ * @param {Object} config - Loaded configuration
+ * @param {Object} logger - Logger instance
+ * @returns {Promise<Array>} Array of loaded plugins
+ */
+export function loadPlugins(configPath: string | null, config: any, logger: any): Promise<any[]>;

package/dist/types/utils/config-loader.d.ts

@@ -2,7 +2,6 @@ export function loadConfig(configPath?: any, cliOverrides?: {}): Promise<{
     server: {
         port: number;
         timeout: number;
-        screenshotPath: string;
     };
     build: {
         name: string;
@@ -19,6 +18,7 @@ export function loadConfig(configPath?: any, cliOverrides?: {}): Promise<{
     tdd: {
         openReport: boolean;
     };
+    plugins: any[];
     apiKey: string;
     apiUrl: string;
 }>;

package/dist/types/utils/config-schema.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Validate Vizzly configuration
+ * @param {unknown} config - Configuration to validate
+ * @returns {Object} Validated configuration
+ * @throws {ZodError} If validation fails
+ */
+export function validateVizzlyConfig(config: unknown): any;
+/**
+ * Safely validate with defaults if config is missing
+ * @param {unknown} config - Configuration to validate (can be undefined)
+ * @returns {Object} Validated configuration with defaults
+ */
+export function validateVizzlyConfigWithDefaults(config: unknown): any;
+/**
+ * Core Vizzly configuration schema
+ * Allows plugin-specific keys with passthrough for extensibility
+ */
+export let vizzlyConfigSchema: z.ZodDefault<z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    apiUrl: z.ZodOptional<z.ZodString>;
+    server: z.ZodDefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+        timeout: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        port?: number;
+        timeout?: number;
+    }, {
+        port?: number;
+        timeout?: number;
+    }>>;
+    build: z.ZodDefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        environment: z.ZodDefault<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+        commit: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name?: string;
+        message?: string;
+        environment?: string;
+        branch?: string;
+        commit?: string;
+    }, {
+        name?: string;
+        message?: string;
+        environment?: string;
+        branch?: string;
+        commit?: string;
+    }>>;
+    upload: z.ZodDefault<z.ZodObject<{
+        screenshotsDir: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+        batchSize: z.ZodDefault<z.ZodNumber>;
+        timeout: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        timeout?: number;
+        screenshotsDir?: string | string[];
+        batchSize?: number;
+    }, {
+        timeout?: number;
+        screenshotsDir?: string | string[];
+        batchSize?: number;
+    }>>;
+    comparison: z.ZodDefault<z.ZodObject<{
+        threshold: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        threshold?: number;
+    }, {
+        threshold?: number;
+    }>>;
+    tdd: z.ZodDefault<z.ZodObject<{
+        openReport: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        openReport?: boolean;
+    }, {
+        openReport?: boolean;
+    }>>;
+    plugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    parallelId: z.ZodOptional<z.ZodString>;
+    baselineBuildId: z.ZodOptional<z.ZodString>;
+    baselineComparisonId: z.ZodOptional<z.ZodString>;
+    eager: z.ZodOptional<z.ZodBoolean>;
+    wait: z.ZodOptional<z.ZodBoolean>;
+    allowNoToken: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    apiUrl: z.ZodOptional<z.ZodString>;
+    server: z.ZodDefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+        timeout: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        port?: number;
+        timeout?: number;
+    }, {
+        port?: number;
+        timeout?: number;
+    }>>;
+    build: z.ZodDefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        environment: z.ZodDefault<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+        commit: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name?: string;
+        message?: string;
+        environment?: string;
+        branch?: string;
+        commit?: string;
+    }, {
+        name?: string;
+        message?: string;
+        environment?: string;
+        branch?: string;
+        commit?: string;
+    }>>;
+    upload: z.ZodDefault<z.ZodObject<{
+        screenshotsDir: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+        batchSize: z.ZodDefault<z.ZodNumber>;
+        timeout: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        timeout?: number;
+        screenshotsDir?: string | string[];
+        batchSize?: number;
+    }, {
+        timeout?: number;
+        screenshotsDir?: string | string[];
+        batchSize?: number;
+    }>>;
+    comparison: z.ZodDefault<z.ZodObject<{
+        threshold: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        threshold?: number;
+    }, {
+        threshold?: number;
+    }>>;
+    tdd: z.ZodDefault<z.ZodObject<{
+        openReport: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        openReport?: boolean;
+    }, {
+        openReport?: boolean;
+    }>>;
+    plugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    parallelId: z.ZodOptional<z.ZodString>;
+    baselineBuildId: z.ZodOptional<z.ZodString>;
+    baselineComparisonId: z.ZodOptional<z.ZodString>;
+    eager: z.ZodOptional<z.ZodBoolean>;
+    wait: z.ZodOptional<z.ZodBoolean>;
+    allowNoToken: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    apiUrl: z.ZodOptional<z.ZodString>;
+    server: z.ZodDefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+        timeout: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        port?: number;
+        timeout?: number;
+    }, {
+        port?: number;
+        timeout?: number;
+    }>>;
+    build: z.ZodDefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        environment: z.ZodDefault<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+        commit: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name?: string;
+        message?: string;
+        environment?: string;
+        branch?: string;
+        commit?: string;
+    }, {
+        name?: string;
+        message?: string;
+        environment?: string;
+        branch?: string;
+        commit?: string;
+    }>>;
+    upload: z.ZodDefault<z.ZodObject<{
+        screenshotsDir: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+        batchSize: z.ZodDefault<z.ZodNumber>;
+        timeout: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        timeout?: number;
+        screenshotsDir?: string | string[];
+        batchSize?: number;
+    }, {
+        timeout?: number;
+        screenshotsDir?: string | string[];
+        batchSize?: number;
+    }>>;
+    comparison: z.ZodDefault<z.ZodObject<{
+        threshold: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        threshold?: number;
+    }, {
+        threshold?: number;
+    }>>;
+    tdd: z.ZodDefault<z.ZodObject<{
+        openReport: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        openReport?: boolean;
+    }, {
+        openReport?: boolean;
+    }>>;
+    plugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    parallelId: z.ZodOptional<z.ZodString>;
+    baselineBuildId: z.ZodOptional<z.ZodString>;
+    baselineComparisonId: z.ZodOptional<z.ZodString>;
+    eager: z.ZodOptional<z.ZodBoolean>;
+    wait: z.ZodOptional<z.ZodBoolean>;
+    allowNoToken: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>>;
+import { z } from 'zod';

package/dist/utils/config-loader.js

@@ -1,6 +1,7 @@
 import { cosmiconfigSync } from 'cosmiconfig';
 import { resolve } from 'path';
 import { getApiToken, getApiUrl, getParallelId } from './environment-config.js';
+import { validateVizzlyConfigWithDefaults } from './config-schema.js';
 const DEFAULT_CONFIG = {
   // API Configuration
   apiKey: getApiToken(),
@@ -8,8 +9,7 @@ const DEFAULT_CONFIG = {
   // Server Configuration (for run command)
   server: {
     port: 47392,
-    timeout: 30000,
-    screenshotPath: '/screenshot'
+    timeout: 30000
   },
   // Build Configuration
   build: {
@@ -29,9 +29,23 @@ const DEFAULT_CONFIG = {
   // TDD Configuration
   tdd: {
     openReport: false // Whether to auto-open HTML report in browser
-  }
+  },
+  // Plugins
+  plugins: []
 };
 export async function loadConfig(configPath = null, cliOverrides = {}) {
+  // 1. Load from config file using cosmiconfig
+  const explorer = cosmiconfigSync('vizzly');
+  const result = configPath ? explorer.load(configPath) : explorer.search();
+  let fileConfig = {};
+  if (result && result.config) {
+    // Handle ESM default export (cosmiconfig wraps it in { default: {...} })
+    fileConfig = result.config.default || result.config;
+  }
+
+  // 2. Validate config file using Zod schema
+  const validatedFileConfig = validateVizzlyConfigWithDefaults(fileConfig);
+
   // Create a proper clone of the default config to avoid shared object references
   const config = {
     ...DEFAULT_CONFIG,
@@ -49,17 +63,14 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
     },
     tdd: {
       ...DEFAULT_CONFIG.tdd
-    }
+    },
+    plugins: [...DEFAULT_CONFIG.plugins]
   };
 
-  // 1. Load from config file using cosmiconfig
-  const explorer = cosmiconfigSync('vizzly');
-  const result = configPath ? explorer.load(configPath) : explorer.search();
-  if (result && result.config) {
-    mergeConfig(config, result.config);
-  }
+  // Merge validated file config
+  mergeConfig(config, validatedFileConfig);
 
-  // 2. Override with environment variables
+  // 3. Override with environment variables
   const envApiKey = getApiToken();
   const envApiUrl = getApiUrl();
   const envParallelId = getParallelId();
@@ -67,7 +78,7 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
   if (envApiUrl !== 'https://app.vizzly.dev') config.apiUrl = envApiUrl;
   if (envParallelId) config.parallelId = envParallelId;
 
-  // 3. Apply CLI overrides (highest priority)
+  // 4. Apply CLI overrides (highest priority)
   applyCLIOverrides(config, cliOverrides);
   return config;
 }

package/dist/utils/config-schema.js

@@ -0,0 +1,134 @@
+/**
+ * Configuration schema validation for Vizzly CLI
+ * Uses Zod for runtime validation
+ */
+
+import { z } from 'zod';
+
+/**
+ * Server configuration schema
+ */
+let serverSchema = z.object({
+  port: z.number().int().positive().default(47392),
+  timeout: z.number().int().positive().default(30000)
+});
+
+/**
+ * Build configuration schema
+ */
+let buildSchema = z.object({
+  name: z.string().default('Build {timestamp}'),
+  environment: z.string().default('test'),
+  branch: z.string().optional(),
+  commit: z.string().optional(),
+  message: z.string().optional()
+});
+
+/**
+ * Upload configuration schema
+ */
+let uploadSchema = z.object({
+  screenshotsDir: z.union([z.string(), z.array(z.string())]).default('./screenshots'),
+  batchSize: z.number().int().positive().default(10),
+  timeout: z.number().int().positive().default(30000)
+});
+
+/**
+ * Comparison configuration schema
+ */
+let comparisonSchema = z.object({
+  threshold: z.number().min(0).max(1).default(0.1)
+});
+
+/**
+ * TDD configuration schema
+ */
+let tddSchema = z.object({
+  openReport: z.boolean().default(false)
+});
+
+/**
+ * Core Vizzly configuration schema
+ * Allows plugin-specific keys with passthrough for extensibility
+ */
+export let vizzlyConfigSchema = z.object({
+  // Core Vizzly config
+  apiKey: z.string().optional(),
+  apiUrl: z.string().url().optional(),
+  server: serverSchema.default({
+    port: 47392,
+    timeout: 30000
+  }),
+  build: buildSchema.default({
+    name: 'Build {timestamp}',
+    environment: 'test'
+  }),
+  upload: uploadSchema.default({
+    screenshotsDir: './screenshots',
+    batchSize: 10,
+    timeout: 30000
+  }),
+  comparison: comparisonSchema.default({
+    threshold: 0.1
+  }),
+  tdd: tddSchema.default({
+    openReport: false
+  }),
+  plugins: z.array(z.string()).default([]),
+  // Additional optional fields
+  parallelId: z.string().optional(),
+  baselineBuildId: z.string().optional(),
+  baselineComparisonId: z.string().optional(),
+  eager: z.boolean().optional(),
+  wait: z.boolean().optional(),
+  allowNoToken: z.boolean().optional()
+}).passthrough() // Allow plugin-specific keys like `staticSite`, `storybook`, etc.
+.default({
+  server: {
+    port: 47392,
+    timeout: 30000
+  },
+  build: {
+    name: 'Build {timestamp}',
+    environment: 'test'
+  },
+  upload: {
+    screenshotsDir: './screenshots',
+    batchSize: 10,
+    timeout: 30000
+  },
+  comparison: {
+    threshold: 0.1
+  },
+  tdd: {
+    openReport: false
+  },
+  plugins: []
+});
+
+/**
+ * Validate Vizzly configuration
+ * @param {unknown} config - Configuration to validate
+ * @returns {Object} Validated configuration
+ * @throws {ZodError} If validation fails
+ */
+export function validateVizzlyConfig(config) {
+  try {
+    return vizzlyConfigSchema.parse(config);
+  } catch (error) {
+    // Re-throw with more context
+    throw new Error(`Invalid Vizzly configuration: ${error.message}\n\n` + `Please check your vizzly.config.js file.\n` + `See https://vizzly.dev/docs/configuration for configuration options.`);
+  }
+}
+
+/**
+ * Safely validate with defaults if config is missing
+ * @param {unknown} config - Configuration to validate (can be undefined)
+ * @returns {Object} Validated configuration with defaults
+ */
+export function validateVizzlyConfigWithDefaults(config) {
+  if (!config) {
+    return vizzlyConfigSchema.parse({});
+  }
+  return validateVizzlyConfig(config);
+}

package/docs/api-reference.md

@@ -476,8 +476,7 @@ Configuration loaded via cosmiconfig in this order:
   // Server Configuration (for run command)
   server: {
     port: number,              // Server port (default: 47392)
-    timeout: number,           // Timeout in ms (default: 30000)
-    screenshotPath: string     // Screenshot endpoint path
+    timeout: number            // Timeout in ms (default: 30000)
   },
 
   // Build Configuration