@vizzly-testing/cli 0.9.0 → 0.10.0

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
 
@@ -125,10 +131,10 @@ vizzly run "npm test" --parallel-id "ci-run-123"  # For parallel CI builds
 For local visual testing with immediate feedback, use the dedicated `tdd` command:
 
 ```bash
-# Start interactive TDD dashboard
+# Start interactive TDD dashboard (runs in background)
 vizzly tdd start
 
-# Run your tests in watch mode
+# Run your tests in watch mode (same terminal or new one)
 npm test -- --watch
 
 # View the dashboard at http://localhost:47392
@@ -160,7 +166,7 @@ vizzly tdd stop
 - `--threshold <number>` - Comparison threshold (0-1, default: 0.1)
 - `--port <port>` - Server port (default: 47392)
 - `--timeout <ms>` - Server timeout (default: 30000)
-- `--daemon` - Run server in background (start command only)
+- `--open` - Auto-open dashboard in browser (start command only)
 
 ### Setup and Status Commands
 ```bash
@@ -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

@@ -5,12 +5,55 @@ import { init } from './commands/init.js';
 import { uploadCommand, validateUploadOptions } from './commands/upload.js';
 import { runCommand, validateRunOptions } from './commands/run.js';
 import { tddCommand, validateTddOptions } from './commands/tdd.js';
-import { tddStartCommand, tddStopCommand, tddStatusCommand } from './commands/tdd-daemon.js';
+import { tddStartCommand, tddStopCommand, tddStatusCommand, runDaemonChild } from './commands/tdd-daemon.js';
 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);
+try {
+  let 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({
@@ -35,8 +78,14 @@ program.command('upload').description('Upload screenshots to Vizzly').argument('
 const tddCmd = program.command('tdd').description('Run tests in TDD mode with local visual comparisons');
 
 // TDD Start - Background server
-tddCmd.command('start').description('Start background TDD server').option('--port <port>', 'Port for screenshot server', '47392').option('--open', 'Open dashboard in browser').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--token <token>', 'API token override').action(async options => {
+tddCmd.command('start').description('Start background TDD server').option('--port <port>', 'Port for screenshot server', '47392').option('--open', 'Open dashboard in browser').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--token <token>', 'API token override').option('--daemon-child', 'Internal: run as daemon child process').action(async options => {
   const globalOptions = program.opts();
+
+  // If this is a daemon child process, run the server directly
+  if (options.daemonChild) {
+    await runDaemonChild(options, globalOptions);
+    return;
+  }
   await tddStartCommand(options, globalOptions);
 });
 

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

@@ -38,15 +38,10 @@ 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',
-
   // Server configuration (for run command)
   server: {
     port: 47392,
-    timeout: 30000,
-    screenshotPath: '/screenshot'
+    timeout: 30000
   },
 
   // Build configuration

package/dist/commands/tdd-daemon.js

@@ -1,4 +1,4 @@
-import { writeFileSync, readFileSync, existsSync, unlinkSync, mkdirSync } from 'fs';
+import { writeFileSync, readFileSync, existsSync, unlinkSync, mkdirSync, openSync } from 'fs';
 import { join } from 'path';
 import { spawn } from 'child_process';
 import { ConsoleUI } from '../utils/console-ui.js';
@@ -36,17 +36,76 @@ export async function tddStartCommand(options = {}, globalOptions = {}) {
     }
     const port = options.port || 47392;
 
-    // Use existing tddCommand but with daemon mode - this will start and keep running
+    // Prepare log files for daemon output
+    const logFile = join(vizzlyDir, 'daemon.log');
+    const errorFile = join(vizzlyDir, 'daemon-error.log');
+
+    // Spawn detached child process to run the server
+    const child = spawn(process.execPath, [process.argv[1],
+    // CLI entry point
+    'tdd', 'start', '--daemon-child',
+    // Special flag for child process
+    '--port', port.toString(), ...(options.open ? ['--open'] : []), ...(options.baselineBuild ? ['--baseline-build', options.baselineBuild] : []), ...(options.baselineComparison ? ['--baseline-comparison', options.baselineComparison] : []), ...(options.environment ? ['--environment', options.environment] : []), ...(options.threshold !== undefined ? ['--threshold', options.threshold.toString()] : []), ...(options.timeout ? ['--timeout', options.timeout] : []), ...(options.token ? ['--token', options.token] : []), ...(globalOptions.json ? ['--json'] : []), ...(globalOptions.verbose ? ['--verbose'] : []), ...(globalOptions.noColor ? ['--no-color'] : [])], {
+      detached: true,
+      stdio: ['ignore', openSync(logFile, 'a'), openSync(errorFile, 'a')],
+      cwd: process.cwd()
+    });
+
+    // Unref so parent can exit
+    child.unref();
+
+    // Verify server started with retries
+    const maxRetries = 10;
+    const retryDelay = 200; // Start with 200ms
+    let running = false;
+    for (let i = 0; i < maxRetries && !running; i++) {
+      await new Promise(resolve => setTimeout(resolve, retryDelay * (i + 1)));
+      running = await isServerRunning(port);
+    }
+    if (!running) {
+      ui.error('Failed to start TDD server - server not responding to health checks');
+      process.exit(1);
+    }
+    ui.success(`TDD server started at http://localhost:${port}`);
+    ui.info('');
+    ui.info('Dashboard URLs:');
+    ui.info(`  Comparisons: http://localhost:${port}/`);
+    ui.info(`  Stats:       http://localhost:${port}/stats`);
+    ui.info('');
+    ui.info('Next steps:');
+    ui.info('  1. Run your tests (any test runner)');
+    ui.info('  2. Open the dashboard in your browser');
+    ui.info('  3. Manage baselines in the Stats view');
+    ui.info('');
+    ui.info('Stop server: npx vizzly tdd stop');
+    if (options.open) {
+      openDashboard(port);
+    }
+  } catch (error) {
+    ui.error('Failed to start TDD daemon', error);
+    process.exit(1);
+  }
+}
+
+/**
+ * Internal function to run server in child process
+ * This is called when --daemon-child flag is present
+ * @private
+ */
+export async function runDaemonChild(options = {}, globalOptions = {}) {
+  const vizzlyDir = join(process.cwd(), '.vizzly');
+  const port = options.port || 47392;
+  try {
+    // Use existing tddCommand but with daemon mode
     const {
       cleanup
     } = await tddCommand(null,
     // No test command - server only
     {
       ...options,
-      daemon: true // Flag to indicate daemon mode
+      daemon: true
     }, globalOptions);
 
-    // The server is now running in this process
     // Store our PID for the stop command
     const pidFile = join(vizzlyDir, 'server.pid');
     writeFileSync(pidFile, process.pid.toString());
@@ -56,25 +115,9 @@ export async function tddStartCommand(options = {}, globalOptions = {}) {
       startTime: Date.now()
     };
     writeFileSync(join(vizzlyDir, 'server.json'), JSON.stringify(serverInfo, null, 2));
-    ui.success(`TDD server started at http://localhost:${port}`);
-    ui.info('');
-    ui.info('Dashboard URLs:');
-    ui.info(`  Comparisons: http://localhost:${port}/`);
-    ui.info(`  Stats:       http://localhost:${port}/stats`);
-    ui.info('');
-    ui.info('Next steps:');
-    ui.info('  1. Run your tests (any test runner)');
-    ui.info('  2. Open the dashboard in your browser');
-    ui.info('  3. Manage baselines in the Stats view');
-    ui.info('');
-    ui.info('Stop server: npx vizzly tdd stop');
-    if (options.open) {
-      openDashboard(port);
-    }
 
     // Set up graceful shutdown
-    const handleShutdown = async signal => {
-      ui.info(`\nReceived ${signal}, shutting down gracefully...`);
+    const handleShutdown = async () => {
       try {
         // Clean up PID files
         if (existsSync(pidFile)) unlinkSync(pidFile);
@@ -83,21 +126,28 @@ export async function tddStartCommand(options = {}, globalOptions = {}) {
 
         // Use the cleanup function from tddCommand
         await cleanup();
-        ui.success('TDD server stopped');
-      } catch (error) {
-        ui.error('Error during shutdown:', error);
+      } catch {
+        // Silent cleanup in daemon
       }
       process.exit(0);
     };
 
     // Register signal handlers
-    process.on('SIGINT', () => handleShutdown('SIGINT'));
-    process.on('SIGTERM', () => handleShutdown('SIGTERM'));
+    process.on('SIGINT', () => handleShutdown());
+    process.on('SIGTERM', () => handleShutdown());
 
     // Keep process alive
     process.stdin.resume();
   } catch (error) {
-    ui.error('Failed to start TDD daemon', error);
+    // Log error to file for debugging
+    const logFile = join(vizzlyDir, 'daemon-error.log');
+    try {
+      writeFileSync(logFile, `[${new Date().toISOString()}] ${error.stack || error}\n`, {
+        flag: 'a'
+      });
+    } catch {
+      // Silent failure if we can't write log
+    }
     process.exit(1);
   }
 }

package/dist/plugin-loader.js

@@ -0,0 +1,183 @@
+import { glob } from 'glob';
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { pathToFileURL } from 'url';
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * Validate plugin has required structure
+ * @param {Object} plugin - Plugin object
+ * @throws {Error} If plugin structure is invalid
+ */
+function validatePluginStructure(plugin) {
+  if (!plugin || typeof plugin !== 'object') {
+    throw new Error('Plugin must export an object');
+  }
+  if (!plugin.name || typeof plugin.name !== 'string') {
+    throw new Error('Plugin must have a name (string)');
+  }
+  if (!plugin.register || typeof plugin.register !== 'function') {
+    throw new Error('Plugin must have a register function');
+  }
+  if (plugin.version && typeof plugin.version !== 'string') {
+    throw new Error('Plugin version must be a string');
+  }
+}
+
+/**
+ * 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);
+  }
+}