@vizzly-testing/cli 0.9.1 → 0.10.0

package/docs/plugins.md

@@ -0,0 +1,496 @@
+# Vizzly Plugin System
+
+The Vizzly CLI supports a powerful plugin system that allows you to extend its functionality with
+custom commands. This enables community contributions and specialized integrations while keeping the
+core CLI lean and focused.
+
+## Overview
+
+Plugins are JavaScript modules that export a simple registration function. The CLI automatically
+discovers plugins from `node_modules/@vizzly-testing/*` or loads them explicitly from your config
+file.
+
+## Benefits
+
+- **Zero Configuration** - Just `npm install` and the plugin is available
+- **Shared Infrastructure** - Plugins get access to config, logger, and services
+- **Independent Releases** - Plugins can iterate without requiring CLI updates
+- **Smaller Core** - Keep the main CLI lean by moving optional features to plugins
+- **Community Extensible** - Anyone can build and share plugins
+
+## Using Plugins
+
+### Official Plugins
+
+Official Vizzly plugins are published under the `@vizzly-testing/*` scope and are automatically
+discovered:
+
+```bash
+# Install plugin
+npm install @vizzly-testing/storybook
+
+# Use immediately - no configuration needed!
+vizzly storybook ./storybook-static
+
+# Plugin commands appear in help
+vizzly --help
+```
+
+### Community Plugins
+
+You can use community plugins or your own local plugins by configuring them explicitly:
+
+```javascript
+// vizzly.config.js
+export default {
+  plugins: [
+    './my-custom-plugin.js',        // Local file path
+    'npm-package-name',             // npm package name
+  ],
+};
+```
+
+This is useful for:
+- Local plugin development and testing
+- Private/internal company plugins
+- Community plugins not in the `@vizzly-testing` scope
+- Custom workflow automation
+
+## Creating a Plugin
+
+### Basic Plugin Structure
+
+A plugin is a JavaScript module that exports an object with `name` and a `register` function:
+
+```javascript
+// my-plugin.js
+export default {
+  name: 'my-plugin',
+  version: '1.0.0', // Optional but recommended
+
+  register(program, { config, logger, services }) {
+    // Register your command with Commander.js
+    program
+      .command('my-command <arg>')
+      .description('Description of my command')
+      .option('--option <value>', 'An option')
+      .action(async (arg, options) => {
+        logger.info(`Running my-command with ${arg}`);
+
+        // Access shared services if needed
+        let apiService = await services.get('apiService');
+
+        // Your command logic here
+      });
+  }
+};
+```
+
+### Plugin Interface
+
+#### Required Fields
+
+- **`name`** (string) - Unique identifier for your plugin
+- **`register`** (function) - Called during CLI initialization to register commands
+
+#### Optional Fields
+
+- **`version`** (string) - Plugin version (recommended for debugging and compatibility)
+
+#### Register Function Parameters
+
+The `register` function receives two arguments:
+
+1. **`program`** - [Commander.js](https://github.com/tj/commander.js) program instance for registering commands
+2. **`context`** - Object containing:
+   - `config` - Merged Vizzly configuration object
+   - `logger` - Shared logger instance with `.debug()`, `.info()`, `.warn()`, `.error()` methods
+   - `services` - Service container with access to internal Vizzly services
+
+### Available Services
+
+Plugins can access these services from the container:
+
+- **`logger`** - Component logger for consistent output
+- **`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
+
+Example accessing a service:
+
+```javascript
+register(program, { config, logger, services }) {
+  program
+    .command('upload-screenshots <dir>')
+    .action(async (dir) => {
+      let uploader = await services.get('uploader');
+      await uploader.uploadScreenshots(screenshots);
+    });
+}
+```
+
+## Local Plugin Development
+
+### Setup
+
+1. Create your plugin file:
+
+```bash
+mkdir -p plugins
+touch plugins/my-plugin.js
+```
+
+2. Write your plugin:
+
+```javascript
+// plugins/my-plugin.js
+export default {
+  name: 'my-plugin',
+  version: '1.0.0',
+  register(program, { config, logger }) {
+    program
+      .command('greet <name>')
+      .description('Greet someone')
+      .action((name) => {
+        logger.info(`Hello, ${name}!`);
+      });
+  }
+};
+```
+
+3. Configure Vizzly to load your plugin:
+
+```javascript
+// vizzly.config.js
+export default {
+  plugins: ['./plugins/my-plugin.js'],
+};
+```
+
+4. Test your plugin:
+
+```bash
+vizzly --help          # See your command listed
+vizzly greet World     # Test your command
+```
+
+### Package Structure (For Distribution)
+
+If you want to share your plugin via npm:
+
+```
+my-vizzly-plugin/
+├── package.json
+├── plugin.js          # Main plugin file
+├── lib/               # Plugin implementation
+├── README.md
+└── tests/
+```
+
+Add a `vizzly.plugin` field to your `package.json`:
+
+```json
+{
+  "name": "vizzly-plugin-custom",
+  "version": "1.0.0",
+  "description": "My custom Vizzly plugin",
+  "main": "./lib/index.js",
+  "vizzly": {
+    "plugin": "./plugin.js"
+  },
+  "keywords": ["vizzly", "vizzly-plugin"],
+  "peerDependencies": {
+    "@vizzly-testing/cli": "^0.9.0"
+  }
+}
+```
+
+Users can then install and use your plugin:
+
+```bash
+npm install vizzly-plugin-custom
+```
+
+```javascript
+// vizzly.config.js
+export default {
+  plugins: ['vizzly-plugin-custom'],
+};
+```
+
+## Best Practices
+
+### Error Handling
+
+Always handle errors gracefully and provide helpful error messages:
+
+```javascript
+register(program, { logger }) {
+  program
+    .command('process <file>')
+    .action(async (file) => {
+      try {
+        if (!existsSync(file)) {
+          logger.error(`File not found: ${file}`);
+          process.exit(1);
+        }
+        // Process file...
+      } catch (error) {
+        logger.error(`Failed to process file: ${error.message}`);
+        process.exit(1);
+      }
+    });
+}
+```
+
+### Logging
+
+Use the provided logger for consistent output across all CLI commands:
+
+```javascript
+logger.debug('Detailed debug info');   // Only shown with --verbose
+logger.info('Normal information');     // Standard output
+logger.warn('Warning message');        // Warning output
+logger.error('Error message');         // Error output
+```
+
+### Async Operations
+
+Use async/await for asynchronous operations:
+
+```javascript
+.action(async (options) => {
+  let service = await services.get('apiService');
+  let result = await service.doSomething();
+  logger.info(`Result: ${result}`);
+});
+```
+
+### Command Naming
+
+Choose clear, descriptive command names that don't conflict with core commands:
+
+✅ **Good command names:**
+- `vizzly storybook`
+- `vizzly import-chromatic`
+- `vizzly generate-report`
+
+❌ **Avoid these (conflicts with core):**
+- `vizzly run`
+- `vizzly upload`
+- `vizzly init`
+- `vizzly tdd`
+
+### Input Validation
+
+Validate user input and provide helpful error messages:
+
+```javascript
+.action(async (path, options) => {
+  if (!path) {
+    logger.error('Path is required');
+    process.exit(1);
+  }
+
+  if (!existsSync(path)) {
+    logger.error(`Path not found: ${path}`);
+    logger.info('Please provide a valid path to your build directory');
+    process.exit(1);
+  }
+
+  // Continue with logic
+});
+```
+
+### Lazy Loading
+
+Import heavy dependencies only when needed to keep CLI startup fast:
+
+```javascript
+register(program, { logger }) {
+  program
+    .command('process-images <dir>')
+    .action(async (dir) => {
+      // Only import when command runs
+      let { processImages } = await import('./heavy-dependency.js');
+      await processImages(dir);
+    });
+}
+```
+
+## Examples
+
+### Simple Command Plugin
+
+```javascript
+export default {
+  name: 'hello',
+  version: '1.0.0',
+  register(program, { logger }) {
+    program
+      .command('hello <name>')
+      .description('Say hello')
+      .option('-l, --loud', 'Say it loudly')
+      .action((name, options) => {
+        let greeting = `Hello, ${name}!`;
+        if (options.loud) {
+          greeting = greeting.toUpperCase();
+        }
+        logger.info(greeting);
+      });
+  }
+};
+```
+
+### Screenshot Capture Plugin
+
+```javascript
+export default {
+  name: 'storybook',
+  version: '1.0.0',
+  register(program, { config, logger, services }) {
+    program
+      .command('storybook <path>')
+      .description('Capture screenshots from Storybook build')
+      .option('--viewports <list>', 'Comma-separated viewports', '1280x720')
+      .action(async (path, options) => {
+        logger.info(`Crawling Storybook at ${path}`);
+
+        // Import dependencies lazily
+        let { crawlStorybook } = await import('./crawler.js');
+
+        // Capture screenshots
+        let screenshots = await crawlStorybook(path, {
+          viewports: options.viewports.split(','),
+          logger,
+        });
+
+        logger.info(`Captured ${screenshots.length} screenshots`);
+
+        // Upload using Vizzly's uploader service
+        let uploader = await services.get('uploader');
+        await uploader.uploadScreenshots(screenshots);
+
+        logger.info('Upload complete!');
+      });
+  }
+};
+```
+
+### Multi-Command Plugin
+
+```javascript
+export default {
+  name: 'reports',
+  version: '1.0.0',
+  register(program, { logger }) {
+    let reports = program
+      .command('reports')
+      .description('Report generation commands');
+
+    reports
+      .command('generate')
+      .description('Generate a new report')
+      .action(() => {
+        logger.info('Generating report...');
+      });
+
+    reports
+      .command('list')
+      .description('List all reports')
+      .action(() => {
+        logger.info('Listing reports...');
+      });
+  }
+};
+```
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+**Check plugin configuration:**
+
+```bash
+vizzly --verbose --help
+```
+
+This will show debug output about plugin loading.
+
+**Common issues:**
+- File path is incorrect (should be relative to `vizzly.config.js`)
+- Plugin file has syntax errors
+- Missing `export default` statement
+
+### Plugin Command Not Showing
+
+**Verify plugin loaded successfully:**
+
+```bash
+vizzly --verbose --help 2>&1 | grep -i plugin
+```
+
+**Common issues:**
+- Missing `name` or `register` function
+- Command name conflicts with existing commands
+- Plugin threw an error during registration
+
+### Type Errors in Editor
+
+If you're using TypeScript or want better IDE support, you can add JSDoc types:
+
+```javascript
+/**
+ * @param {import('commander').Command} program
+ * @param {Object} context
+ * @param {Object} context.config
+ * @param {Object} context.logger
+ * @param {Object} context.services
+ */
+function register(program, { config, logger, services }) {
+  // Your plugin code with full autocomplete!
+}
+
+export default {
+  name: 'my-plugin',
+  register,
+};
+```
+
+## Contributing a Plugin
+
+### Share Your Plugin
+
+Built a useful plugin? We'd love to feature it! Here's how to share:
+
+1. **Publish to npm** (optional but recommended for reusability)
+2. **Add documentation** - Include a clear README with usage examples
+3. **Open an issue** on the [Vizzly CLI repository](https://github.com/vizzly-testing/cli/issues) with:
+   - Plugin name and description
+   - Link to repository or npm package
+   - Usage example
+   - Screenshots/demo if applicable
+
+### Plugin Ideas
+
+Here are some plugin ideas the community might find useful:
+
+- **Playwright integration** - Automated screenshot capture from Playwright tests
+- **Cypress integration** - Screenshot capture from Cypress tests
+- **Percy migration** - Import screenshots from Percy
+- **Chromatic migration** - Import screenshots from Chromatic
+- **Figma comparison** - Compare designs with Figma files
+- **Image optimization** - Compress screenshots before upload
+- **Custom reporters** - Generate custom HTML/PDF reports
+- **CI/CD integrations** - Specialized workflows for different CI platforms
+
+## Support
+
+Need help building a plugin?
+
+- 📖 [View example plugin source](https://github.com/vizzly-testing/cli/tree/main/examples/custom-plugin)
+- 🐛 [Report issues](https://github.com/vizzly-testing/cli/issues)
+- 📧 [Email support](https://vizzly.dev/support/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -83,7 +83,8 @@
     "dotenv": "^17.2.1",
     "form-data": "^4.0.0",
     "glob": "^11.0.3",
-    "odiff-bin": "^3.2.1"
+    "odiff-bin": "^3.2.1",
+    "zod": "^3.24.1"
   },
   "devDependencies": {
     "@babel/cli": "^7.28.0",
@@ -103,7 +104,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.3",
     "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-hooks": "^6.1.1",
     "postcss": "^8.5.6",
     "prettier": "^3.6.2",
     "react": "^19.1.1",