@vizzly-testing/cli 0.9.1 → 0.10.1

package/README.md

@@ -7,9 +7,13 @@
 
 ## What is Vizzly?
 
-Vizzly is a visual review platform designed for how modern teams work. Instead of recreating your components in a sandboxed environment, Vizzly captures screenshots directly from your functional tests. This means you test the *real thing*, not a snapshot.
+Vizzly is a visual review platform designed for how modern teams work. Instead of recreating your
+components in a sandboxed environment, Vizzly captures screenshots directly from your functional
+tests. This means you test the *real thing*, not a snapshot.
 
-It's fast because we don't render anything—we process the images you provide from any source. Bring screenshots from web apps, mobile apps, or even design mockups, and use our collaborative dashboard to streamline the review process between developers and designers.
+It's fast because we don't render anything—we process the images you provide from any source. Bring
+screenshots from web apps, mobile apps, or even design mockups, and use our collaborative dashboard
+to streamline the review process between developers and designers.
 
 ## Features
 
@@ -73,7 +77,9 @@ await vizzlyScreenshot('homepage', screenshot, {
 });
 ```
 
-> **Multi-Language Support**: Currently available as a JavaScript/Node.js SDK with Python, Ruby, and other language bindings coming soon. The client SDK is lightweight and simply POSTs screenshot data to the CLI for processing.
+> **Multi-Language Support**: Currently available as a JavaScript/Node.js SDK with Python, Ruby, and
+> other language bindings coming soon. The client SDK is lightweight and simply POSTs screenshot
+> data to the CLI for processing.
 
 ## Commands
 
@@ -174,7 +180,8 @@ vizzly doctor --api                 # Include API connectivity checks
 ```
 
 #### Init Command
-Creates a basic `vizzly.config.js` configuration file with sensible defaults. No interactive prompts - just generates a clean config you can customize.
+Creates a basic `vizzly.config.js` configuration file with sensible defaults. No interactive
+prompts - just generates a clean config you can customize.
 
 ```bash
 vizzly init           # Create config file
@@ -217,7 +224,8 @@ VIZZLY_TOKEN=your-token vizzly doctor --api
 vizzly doctor --json
 ```
 
-The dedicated `tdd` command provides fast local development with immediate visual feedback. See the [TDD Mode Guide](./docs/tdd-mode.md) for complete details on local visual testing.
+The dedicated `tdd` command provides fast local development with immediate visual feedback. See the
+[TDD Mode Guide](./docs/tdd-mode.md) for complete details on local visual testing.
 
 ## Configuration
 
@@ -225,20 +233,10 @@ Create a `vizzly.config.js` file with `vizzly init` or manually:
 
 ```javascript
 export default {
-  // API configuration
-  // Set VIZZLY_TOKEN environment variable or uncomment and set here:
-  // apiToken: 'your-token-here',
-
-  // Screenshot configuration
-  screenshots: {
-    directory: './screenshots',
-    formats: ['png']
-  },
-
   // Server configuration
   server: {
     port: 47392,
-    screenshotPath: '/screenshot'
+    timeout: 30000
   },
 
   // Comparison configuration
@@ -368,14 +366,71 @@ Send a screenshot to Vizzly.
 ### `isVizzlyEnabled()`
 Check if Vizzly is enabled in the current environment.
 
+## Plugin Ecosystem
+
+Vizzly supports a powerful plugin system that allows you to extend the CLI with custom
+commands. Plugins are automatically discovered from `@vizzly-testing/*` packages or can be
+explicitly configured.
+
+### Official Plugins
+
+- **[@vizzly-testing/storybook](https://npmjs.com/package/@vizzly-testing/storybook)** *(coming
+  soon)* - Capture screenshots from Storybook builds
+
+### Using Plugins
+
+Plugins under the `@vizzly-testing/*` scope are auto-discovered:
+
+```bash
+# Install plugin
+npm install @vizzly-testing/storybook
+
+# Use immediately - commands are automatically available!
+vizzly storybook ./storybook-static
+
+# Plugin commands show in help
+vizzly --help
+```
+
+### Creating Plugins
+
+You can create your own plugins to add custom commands:
+
+```javascript
+// plugin.js
+export default {
+  name: 'my-plugin',
+  version: '1.0.0',
+  register(program, { config, logger, services }) {
+    program
+      .command('my-command')
+      .description('My custom command')
+      .action(async () => {
+        logger.info('Running my command!');
+      });
+  }
+};
+```
+
+Add to your `vizzly.config.js`:
+
+```javascript
+export default {
+  plugins: ['./plugin.js']
+};
+```
+
+See the [Plugin Development Guide](./docs/plugins.md) for complete documentation and examples.
+
 ## Documentation
 
 - [Getting Started](./docs/getting-started.md)
 - [Upload Command Guide](./docs/upload-command.md)
 - [Test Integration Guide](./docs/test-integration.md)
 - [TDD Mode Guide](./docs/tdd-mode.md)
- - [API Reference](./docs/api-reference.md)
- - [Doctor Command](./docs/doctor-command.md)
+- [Plugin Development](./docs/plugins.md)
+- [API Reference](./docs/api-reference.md)
+- [Doctor Command](./docs/doctor-command.md)
 
 ## Environment Variables
 
@@ -408,7 +463,8 @@ These variables take highest priority over both CLI arguments and automatic git
 
 ## Contributing
 
-We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help makes Vizzly better for everyone.
+We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation,
+your help makes Vizzly better for everyone.
 
 ### Getting Started
 
@@ -437,7 +493,8 @@ Found a bug or have a feature request? Please [open an issue](https://github.com
 
 ### Development Setup
 
-The CLI is built with modern JavaScript and requires Node.js 20+ (LTS). See the development scripts in `package.json` for available commands.
+The CLI is built with modern JavaScript and requires Node.js 20+ (LTS). See the development scripts
+in `package.json` for available commands.
 
 ## License
 

package/dist/cli.js

@@ -10,12 +10,57 @@ import { statusCommand, validateStatusOptions } from './commands/status.js';
 import { finalizeCommand, validateFinalizeOptions } from './commands/finalize.js';
 import { doctorCommand, validateDoctorOptions } from './commands/doctor.js';
 import { getPackageVersion } from './utils/package-info.js';
+import { loadPlugins } from './plugin-loader.js';
+import { loadConfig } from './utils/config-loader.js';
+import { createComponentLogger } from './utils/logger-factory.js';
+import { createServiceContainer } from './container/index.js';
 program.name('vizzly').description('Vizzly CLI for visual regression testing').version(getPackageVersion()).option('-c, --config <path>', 'Config file path').option('--token <token>', 'Vizzly API token').option('-v, --verbose', 'Verbose output').option('--json', 'Machine-readable output').option('--no-color', 'Disable colored output');
+
+// Load plugins before defining commands
+// We need to manually parse to get the config option early
+let configPath = null;
+let verboseMode = false;
+for (let i = 0; i < process.argv.length; i++) {
+  if ((process.argv[i] === '-c' || process.argv[i] === '--config') && process.argv[i + 1]) {
+    configPath = process.argv[i + 1];
+  }
+  if (process.argv[i] === '-v' || process.argv[i] === '--verbose') {
+    verboseMode = true;
+  }
+}
+let config = await loadConfig(configPath, {});
+let logger = createComponentLogger('CLI', {
+  level: config.logLevel || (verboseMode ? 'debug' : 'warn'),
+  verbose: verboseMode || false
+});
+let container = await createServiceContainer(config);
+let plugins = [];
+try {
+  plugins = await loadPlugins(configPath, config, logger);
+  for (let plugin of plugins) {
+    try {
+      // Add timeout protection for plugin registration (5 seconds)
+      let registerPromise = plugin.register(program, {
+        config,
+        logger,
+        services: container
+      });
+      let timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Plugin registration timeout (5s)')), 5000));
+      await Promise.race([registerPromise, timeoutPromise]);
+      logger.debug(`Registered plugin: ${plugin.name}`);
+    } catch (error) {
+      logger.warn(`Failed to register plugin ${plugin.name}: ${error.message}`);
+    }
+  }
+} catch (error) {
+  logger.debug(`Plugin loading failed: ${error.message}`);
+}
 program.command('init').description('Initialize Vizzly in your project').option('--force', 'Overwrite existing configuration').action(async options => {
   const globalOptions = program.opts();
   await init({
     ...globalOptions,
-    ...options
+    ...options,
+    plugins
   });
 });
 program.command('upload').description('Upload screenshots to Vizzly').argument('<path>', 'Path to screenshots directory or file').option('-b, --build-name <name>', 'Build name for grouping').option('-m, --metadata <json>', 'Additional metadata as JSON').option('--batch-size <n>', 'Upload batch size', v => parseInt(v, 10)).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', v => parseInt(v, 10)).option('--branch <branch>', 'Git branch').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (path, options) => {

package/dist/client/index.js

@@ -113,7 +113,6 @@ function createSimpleClient(serverUrl) {
             image: imageBuffer.toString('base64'),
             properties: options,
             threshold: options.threshold || 0,
-            variant: options.variant,
             fullPage: options.fullPage || false
           })
         });
@@ -189,7 +188,6 @@ function createSimpleClient(serverUrl) {
  * @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>}

package/dist/commands/init.js

@@ -3,15 +3,19 @@ import fs from 'fs/promises';
 import path from 'path';
 import { VizzlyError } from '../errors/vizzly-error.js';
 import { createComponentLogger } from '../utils/logger-factory.js';
+import { loadPlugins } from '../plugin-loader.js';
+import { loadConfig } from '../utils/config-loader.js';
+import { z } from 'zod';
 
 /**
  * Simple configuration setup for Vizzly CLI
  */
 export class InitCommand {
-  constructor(logger) {
+  constructor(logger, plugins = []) {
     this.logger = logger || createComponentLogger('INIT', {
       level: 'info'
     });
+    this.plugins = plugins;
   }
   async run(options = {}) {
     this.logger.info('🎯 Initializing Vizzly configuration...\n');
@@ -37,16 +41,11 @@ export class InitCommand {
     }
   }
   async generateConfigFile(configPath) {
-    const configContent = `export default {
-  // API configuration
-  // Set VIZZLY_TOKEN environment variable or uncomment and set here:
-  // apiKey: 'your-token-here',
-
+    let coreConfig = `export default {
   // Server configuration (for run command)
   server: {
     port: 47392,
-    timeout: 30000,
-    screenshotPath: '/screenshot'
+    timeout: 30000
   },
 
   // Build configuration
@@ -70,11 +69,103 @@ export class InitCommand {
   // TDD configuration
   tdd: {
     openReport: false // Whether to auto-open HTML report in browser
-  }
-};
-`;
-    await fs.writeFile(configPath, configContent, 'utf8');
+  }`;
+
+    // Add plugin configurations
+    let pluginConfigs = this.generatePluginConfigs();
+    if (pluginConfigs) {
+      coreConfig += ',\n\n' + pluginConfigs;
+    }
+    coreConfig += '\n};\n';
+    await fs.writeFile(configPath, coreConfig, 'utf8');
     this.logger.info(`📄 Created vizzly.config.js`);
+
+    // Log discovered plugins
+    let pluginsWithConfig = this.plugins.filter(p => p.configSchema);
+    if (pluginsWithConfig.length > 0) {
+      this.logger.info(`   Added config for ${pluginsWithConfig.length} plugin(s):`);
+      pluginsWithConfig.forEach(p => {
+        this.logger.info(`   - ${p.name}`);
+      });
+    }
+  }
+
+  /**
+   * Generate configuration sections for plugins
+   * @returns {string} Plugin config sections as formatted string
+   */
+  generatePluginConfigs() {
+    let sections = [];
+    for (let plugin of this.plugins) {
+      if (plugin.configSchema) {
+        let configStr = this.formatPluginConfig(plugin);
+        if (configStr) {
+          sections.push(configStr);
+        }
+      }
+    }
+    return sections.length > 0 ? sections.join(',\n\n') : '';
+  }
+
+  /**
+   * Format a plugin's config schema as JavaScript code
+   * @param {Object} plugin - Plugin with configSchema
+   * @returns {string} Formatted config string
+   */
+  formatPluginConfig(plugin) {
+    try {
+      // Validate config schema structure with Zod (defensive check)
+      let configValueSchema = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(configValueSchema), z.record(configValueSchema)]));
+      let configSchemaValidator = z.record(configValueSchema);
+      configSchemaValidator.parse(plugin.configSchema);
+      let configEntries = [];
+      for (let [key, value] of Object.entries(plugin.configSchema)) {
+        let formattedValue = this.formatValue(value, 1);
+        configEntries.push(`  // ${plugin.name} plugin configuration\n  ${key}: ${formattedValue}`);
+      }
+      return configEntries.join(',\n\n');
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        let messages = error.errors.map(e => `${e.path.join('.')}: ${e.message}`);
+        this.logger.warn(`Invalid config schema for plugin ${plugin.name}: ${messages.join(', ')}`);
+      } else {
+        this.logger.warn(`Failed to format config for plugin ${plugin.name}: ${error.message}`);
+      }
+      return '';
+    }
+  }
+
+  /**
+   * Format a JavaScript value with proper indentation
+   * @param {*} value - Value to format
+   * @param {number} depth - Current indentation depth
+   * @returns {string} Formatted value
+   */
+  formatValue(value, depth = 0) {
+    let indent = '  '.repeat(depth);
+    let nextIndent = '  '.repeat(depth + 1);
+    if (value === null) return 'null';
+    if (value === undefined) return 'undefined';
+    if (typeof value === 'string') return `'${value.replace(/'/g, "\\'")}'`;
+    if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+    if (Array.isArray(value)) {
+      if (value.length === 0) return '[]';
+      let items = value.map(item => {
+        let formatted = this.formatValue(item, depth + 1);
+        return `${nextIndent}${formatted}`;
+      });
+      return `[\n${items.join(',\n')}\n${indent}]`;
+    }
+    if (typeof value === 'object') {
+      let entries = Object.entries(value);
+      if (entries.length === 0) return '{}';
+      let props = entries.map(([k, v]) => {
+        let formatted = this.formatValue(v, depth + 1);
+        return `${nextIndent}${k}: ${formatted}`;
+      });
+      return `{\n${props.join(',\n')}\n${indent}}`;
+    }
+    return String(value);
   }
   showNextSteps() {
     this.logger.info('\n📚 Next steps:');
@@ -97,12 +188,28 @@ export class InitCommand {
 
 // Export factory function for CLI
 export function createInitCommand(options) {
-  const command = new InitCommand(options.logger);
+  const command = new InitCommand(options.logger, options.plugins);
   return () => command.run(options);
 }
 
 // Simple export for direct CLI usage
 export async function init(options = {}) {
-  const command = new InitCommand();
+  let plugins = [];
+
+  // Try to load plugins if not provided
+  if (!options.plugins) {
+    try {
+      let config = await loadConfig(options.config, {});
+      let logger = createComponentLogger('INIT', {
+        level: 'debug'
+      });
+      plugins = await loadPlugins(options.config, config, logger);
+    } catch {
+      // Silent fail - plugins are optional for init
+    }
+  } else {
+    plugins = options.plugins;
+  }
+  const command = new InitCommand(null, plugins);
   return await command.run(options);
 }

package/dist/plugin-loader.js

@@ -0,0 +1,204 @@
+import { glob } from 'glob';
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { pathToFileURL } from 'url';
+import { z } from 'zod';
+
+/**
+ * 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 async function loadPlugins(configPath, config, logger) {
+  let plugins = [];
+  let loadedNames = new Set();
+
+  // 1. Auto-discover plugins from @vizzly-testing/* packages
+  let discoveredPlugins = await discoverInstalledPlugins(logger);
+  for (let pluginInfo of discoveredPlugins) {
+    try {
+      let plugin = await loadPlugin(pluginInfo.path, logger);
+      if (plugin && !loadedNames.has(plugin.name)) {
+        plugins.push(plugin);
+        loadedNames.add(plugin.name);
+        logger.debug(`Loaded plugin: ${plugin.name}@${plugin.version || 'unknown'}`);
+      }
+    } catch (error) {
+      logger.warn(`Failed to load auto-discovered plugin from ${pluginInfo.packageName}: ${error.message}`);
+    }
+  }
+
+  // 2. Load explicit plugins from config
+  if (config?.plugins && Array.isArray(config.plugins)) {
+    for (let pluginSpec of config.plugins) {
+      try {
+        let pluginPath = resolvePluginPath(pluginSpec, configPath);
+        let plugin = await loadPlugin(pluginPath, logger);
+        if (plugin && !loadedNames.has(plugin.name)) {
+          plugins.push(plugin);
+          loadedNames.add(plugin.name);
+          logger.debug(`Loaded plugin from config: ${plugin.name}@${plugin.version || 'unknown'}`);
+        } else if (plugin && loadedNames.has(plugin.name)) {
+          let existingPlugin = plugins.find(p => p.name === plugin.name);
+          logger.warn(`Plugin ${plugin.name} already loaded (v${existingPlugin.version || 'unknown'}), ` + `skipping v${plugin.version || 'unknown'} from config`);
+        }
+      } catch (error) {
+        logger.warn(`Failed to load plugin from config (${pluginSpec}): ${error.message}`);
+      }
+    }
+  }
+  return plugins;
+}
+
+/**
+ * Discover installed plugins from node_modules/@vizzly-testing/*
+ * @param {Object} logger - Logger instance
+ * @returns {Promise<Array>} Array of plugin info objects
+ */
+async function discoverInstalledPlugins(logger) {
+  let plugins = [];
+  try {
+    // Find all @vizzly-testing packages
+    let packageJsonPaths = await glob('node_modules/@vizzly-testing/*/package.json', {
+      cwd: process.cwd(),
+      absolute: true
+    });
+    for (let pkgPath of packageJsonPaths) {
+      try {
+        let packageJson = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+        // Check if package has a plugin field
+        if (packageJson.vizzly?.plugin) {
+          let pluginRelativePath = packageJson.vizzly.plugin;
+
+          // Security: Ensure plugin path is relative and doesn't traverse up
+          if (pluginRelativePath.startsWith('/') || pluginRelativePath.includes('..')) {
+            logger.warn(`Invalid plugin path in ${packageJson.name}: path must be relative and cannot traverse directories`);
+            continue;
+          }
+
+          // Resolve plugin path relative to package directory
+          let packageDir = dirname(pkgPath);
+          let pluginPath = resolve(packageDir, pluginRelativePath);
+
+          // Additional security: Ensure resolved path is still within package directory
+          if (!pluginPath.startsWith(packageDir)) {
+            logger.warn(`Plugin path escapes package directory: ${packageJson.name}`);
+            continue;
+          }
+          plugins.push({
+            packageName: packageJson.name,
+            path: pluginPath
+          });
+        }
+      } catch (error) {
+        logger.warn(`Failed to parse package.json at ${pkgPath}: ${error.message}`);
+      }
+    }
+  } catch (error) {
+    logger.debug(`Failed to discover plugins: ${error.message}`);
+  }
+  return plugins;
+}
+
+/**
+ * Load a plugin from a file path
+ * @param {string} pluginPath - Path to plugin file
+ * @returns {Promise<Object|null>} Loaded plugin or null
+ */
+async function loadPlugin(pluginPath) {
+  try {
+    // Convert to file URL for ESM import
+    let pluginUrl = pathToFileURL(pluginPath).href;
+
+    // Dynamic import
+    let pluginModule = await import(pluginUrl);
+
+    // Get the default export
+    let plugin = pluginModule.default || pluginModule;
+
+    // Validate plugin structure
+    validatePluginStructure(plugin);
+    return plugin;
+  } catch (error) {
+    let newError = new Error(`Failed to load plugin from ${pluginPath}: ${error.message}`);
+    newError.cause = error;
+    throw newError;
+  }
+}
+
+/**
+ * Zod schema for validating plugin structure
+ */
+const pluginSchema = z.object({
+  name: z.string().min(1, 'Plugin name is required'),
+  version: z.string().optional(),
+  register: z.function(z.tuple([z.any(), z.any()]), z.void()),
+  configSchema: z.record(z.any()).optional()
+});
+
+/**
+ * Zod schema for validating plugin config values
+ * Supports: string, number, boolean, null, arrays, and nested objects
+ */
+const configValueSchema = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(configValueSchema), z.record(configValueSchema)]));
+
+/**
+ * Validate plugin has required structure
+ * @param {Object} plugin - Plugin object
+ * @throws {Error} If plugin structure is invalid
+ */
+function validatePluginStructure(plugin) {
+  try {
+    // Validate basic plugin structure
+    pluginSchema.parse(plugin);
+
+    // If configSchema exists, validate it contains valid config values
+    if (plugin.configSchema) {
+      let configSchemaValidator = z.record(configValueSchema);
+      configSchemaValidator.parse(plugin.configSchema);
+    }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      let messages = error.errors.map(e => `${e.path.join('.')}: ${e.message}`);
+      throw new Error(`Invalid plugin structure: ${messages.join(', ')}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Resolve plugin path from config
+ * @param {string} pluginSpec - Plugin specifier (package name or path)
+ * @param {string|null} configPath - Path to config file
+ * @returns {string} Resolved plugin path
+ */
+function resolvePluginPath(pluginSpec, configPath) {
+  // If it's a package name (starts with @ or is alphanumeric), try to resolve from node_modules
+  if (pluginSpec.startsWith('@') || /^[a-zA-Z0-9-]+$/.test(pluginSpec)) {
+    // Try to resolve as a package
+    try {
+      let packageJsonPath = resolve(process.cwd(), 'node_modules', pluginSpec, 'package.json');
+      let packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+      if (packageJson.vizzly?.plugin) {
+        let packageDir = dirname(packageJsonPath);
+        return resolve(packageDir, packageJson.vizzly.plugin);
+      }
+      throw new Error('Package does not specify a vizzly.plugin field');
+    } catch (error) {
+      throw new Error(`Cannot resolve plugin package ${pluginSpec}: ${error.message}`);
+    }
+  }
+
+  // Otherwise treat as a file path
+  if (configPath) {
+    // Resolve relative to config file
+    let configDir = dirname(configPath);
+    return resolve(configDir, pluginSpec);
+  } else {
+    // Resolve relative to cwd
+    return resolve(process.cwd(), pluginSpec);
+  }
+}