@vizzly-testing/cli 0.10.3 → 0.11.1

package/README.md

@@ -36,16 +36,44 @@ npm install -g @vizzly-testing/cli
 vizzly init
 ```
 
-### Set up your API token
+### Authentication
 
-For local development, create a `.env` file in your project root and add your token:
+Vizzly supports two authentication methods:
 
+**Option 1: User Authentication (Recommended for local development)**
+```bash
+# Authenticate with your Vizzly account
+vizzly login
+
+# Optional: Configure project-specific token
+vizzly project:select
+
+# Run tests
+vizzly run "npm test"
 ```
-VIZZLY_TOKEN=your-api-token
+
+**Option 2: API Token (Recommended for CI/CD)**
+```bash
+# Set via environment variable
+export VIZZLY_TOKEN=your-project-token
+
+# Run tests
+vizzly run "npm test"
+```
+
+For local development with `.env` files:
+```
+VIZZLY_TOKEN=your-project-token
 ```
 
 Then add `.env` to your `.gitignore` file. For CI/CD, use your provider's secret management system.
 
+**Token Priority:**
+1. CLI flag (`--token`)
+2. Environment variable (`VIZZLY_TOKEN`)
+3. Project mapping (configured via `vizzly project:select`)
+4. User access token (from `vizzly login`)
+
 ### Upload existing screenshots
 
 ```bash
@@ -67,14 +95,19 @@ vizzly tdd run "npm test"
 ```javascript
 import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
 
-// Your test framework takes the screenshot
+// Option 1: Using a Buffer
 const screenshot = await page.screenshot();
-
-// Send to Vizzly for review
 await vizzlyScreenshot('homepage', screenshot, {
   browser: 'chrome',
   viewport: '1920x1080'
 });
+
+// Option 2: Using a file path
+await page.screenshot({ path: './screenshots/homepage.png' });
+await vizzlyScreenshot('homepage', './screenshots/homepage.png', {
+  browser: 'chrome',
+  viewport: '1920x1080'
+});
 ```
 
 > **Multi-Language Support**: Currently available as a JavaScript/Node.js SDK with Python, Ruby, and
@@ -83,6 +116,84 @@ await vizzlyScreenshot('homepage', screenshot, {
 
 ## Commands
 
+### Authentication Commands
+
+```bash
+vizzly login                        # Authenticate with your Vizzly account
+vizzly logout                       # Clear stored authentication tokens
+vizzly whoami                       # Show current user and authentication status
+vizzly project:select               # Configure project-specific token
+vizzly project:list                 # Show all configured projects
+vizzly project:token                # Display project token for current directory
+vizzly project:remove               # Remove project configuration
+```
+
+#### Login Command
+Authenticate using OAuth 2.0 device flow. Opens your browser to authorize the CLI with your Vizzly account.
+
+```bash
+# Interactive browser-based login
+vizzly login
+
+# JSON output for scripting
+vizzly login --json
+```
+
+**Features:**
+- Browser auto-opens with pre-filled device code
+- Secure OAuth 2.0 device authorization flow
+- 30-day token expiry with automatic refresh
+- Tokens stored securely in `~/.vizzly/config.json` with 0600 permissions
+
+#### Logout Command
+Clear all stored authentication tokens from your machine.
+
+```bash
+# Clear all tokens
+vizzly logout
+
+# JSON output
+vizzly logout --json
+```
+
+Revokes tokens on the server and removes them from local storage.
+
+#### Whoami Command
+Display current authentication status, user information, and organizations.
+
+```bash
+# Show user and authentication info
+vizzly whoami
+
+# JSON output for scripting
+vizzly whoami --json
+```
+
+Shows:
+- Current user email and name
+- Organizations you belong to
+- Token status and expiry
+- Project mappings (if any)
+
+#### Project Commands
+Configure directory-specific project tokens for multi-project workflows.
+
+```bash
+# Select a project for current directory
+vizzly project:select
+
+# List all configured projects
+vizzly project:list
+
+# Show token for current directory
+vizzly project:token
+
+# Remove project configuration
+vizzly project:remove
+```
+
+**Use case:** Working on multiple Vizzly projects? Configure each project directory with its specific token. The CLI automatically uses the right token based on your current directory.
+
 ### Upload Screenshots
 ```bash
 vizzly upload <directory>           # Upload screenshots from directory
@@ -360,12 +471,52 @@ The `--wait` flag ensures the process:
 ### `vizzlyScreenshot(name, imageBuffer, properties)`
 Send a screenshot to Vizzly.
 - `name` (string): Screenshot identifier
-- `imageBuffer` (Buffer): Image data
+- `imageBuffer` (Buffer | string): Image data as Buffer, or file path to an image
 - `properties` (object): Metadata for organization
 
+**File Path Support:**
+- Accepts both absolute and relative paths
+- Automatically reads the file and converts to Buffer internally
+- Works with any PNG image file
+
 ### `isVizzlyEnabled()`
 Check if Vizzly is enabled in the current environment.
 
+## AI & Editor Integrations
+
+### Claude Code Plugin
+
+Vizzly includes built-in support for [Claude Code](https://claude.com/code), Anthropic's official CLI tool. The integration brings AI-powered visual testing workflows directly into your development environment.
+
+**Features:**
+- 🤖 **AI-assisted debugging** - Get intelligent analysis of visual regressions
+- 📊 **TDD status insights** - Check dashboard status with contextual suggestions
+- 🔍 **Smart diff analysis** - AI helps determine if changes should be accepted or fixed
+- ✨ **Test coverage suggestions** - Get framework-specific screenshot recommendations
+- 🛠️ **Interactive setup** - Guided configuration and CI/CD integration help
+
+**Getting Started with Claude Code:**
+
+1. **Install Claude Code** (if you haven't already):
+   ```bash
+   npm install -g @anthropic-ai/claude-code
+   ```
+
+2. **Install the Vizzly plugin** via Claude Code marketplace:
+   ```
+   /plugin marketplace add vizzly-testing/cli
+   ```
+
+3. **Use AI-powered workflows** with slash commands:
+   ```
+   /vizzly:tdd-status              # Check TDD dashboard with AI insights
+   /vizzly:debug-diff homepage     # Analyze visual failures with AI
+   /vizzly:suggest-screenshots     # Find test coverage gaps
+   /vizzly:setup                   # Interactive setup wizard
+   ```
+
+The plugin works seamlessly with both local TDD mode and cloud builds, providing contextual help based on your current workflow.
+
 ## Plugin Ecosystem
 
 Vizzly supports a powerful plugin system that allows you to extend the CLI with custom
@@ -374,6 +525,7 @@ explicitly configured.
 
 ### Official Plugins
 
+- **Claude Code Integration** *(built-in)* - AI-powered visual testing workflows for Claude Code
 - **[@vizzly-testing/storybook](https://npmjs.com/package/@vizzly-testing/storybook)** *(coming
   soon)* - Capture screenshots from Storybook builds
 
@@ -425,6 +577,7 @@ See the [Plugin Development Guide](./docs/plugins.md) for complete documentation
 ## Documentation
 
 - [Getting Started](./docs/getting-started.md)
+- [Authentication Guide](./docs/authentication.md)
 - [Upload Command Guide](./docs/upload-command.md)
 - [Test Integration Guide](./docs/test-integration.md)
 - [TDD Mode Guide](./docs/tdd-mode.md)
@@ -432,10 +585,17 @@ See the [Plugin Development Guide](./docs/plugins.md) for complete documentation
 - [API Reference](./docs/api-reference.md)
 - [Doctor Command](./docs/doctor-command.md)
 
+**AI & Editor Integrations:**
+- Claude Code Plugin - Built-in support (see [AI & Editor Integrations](#ai--editor-integrations) above)
+
 ## Environment Variables
 
+### Authentication
+- `VIZZLY_TOKEN`: API authentication token (project token or access token). Example: `export VIZZLY_TOKEN=your-token`.
+  - For local development: Use `vizzly login` instead of manually managing tokens
+  - For CI/CD: Use project tokens from environment variables
+
 ### Core Configuration
-- `VIZZLY_TOKEN`: API authentication token. Example: `export VIZZLY_TOKEN=your-token`.
 - `VIZZLY_API_URL`: Override API base URL. Default: `https://app.vizzly.dev`.
 - `VIZZLY_LOG_LEVEL`: Logger level. One of `debug`, `info`, `warn`, `error`. Example: `export VIZZLY_LOG_LEVEL=debug`.
 

package/claude-plugin/.claude-plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "vizzly": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/vizzly-server/index.js"]
+    }
+  }
+}

package/claude-plugin/.claude-plugin/README.md

@@ -0,0 +1,114 @@
+# Vizzly Claude Code Plugin
+
+> Integrate Vizzly visual regression testing seamlessly into your Claude Code workflow
+
+This plugin brings Vizzly's powerful visual testing capabilities directly into Claude Code, helping you debug visual regressions, manage baselines, and integrate visual testing into your development workflow—all with AI assistance.
+
+## Installation
+
+### From GitHub (Recommended)
+
+```bash
+# Add the marketplace
+/plugin marketplace add vizzly-testing/vizzly-cli
+
+# Install the plugin
+/plugin install vizzly@vizzly-marketplace
+```
+
+### From Local Source
+
+```bash
+# Clone the repository
+git clone https://github.com/vizzly-testing/vizzly-cli.git
+cd vizzly-cli
+
+# Add the marketplace
+/plugin marketplace add ./.claude-plugin
+
+# Install the plugin
+/plugin install vizzly@vizzly-marketplace
+```
+
+## Features
+
+### 🔍 **TDD Status Checking**
+- `/vizzly:tdd-status` - Check current TDD status and comparison results
+- See failed/new/passed screenshot counts
+- Direct links to diff images and dashboard
+
+### 🐛 **Smart Diff Analysis**
+- `/vizzly:debug-diff <screenshot-name>` - Analyze visual regression failures
+- AI-powered analysis with contextual suggestions
+- Guidance on whether to accept or fix changes
+
+### 💡 **Screenshot Suggestions**
+- `/vizzly:suggest-screenshots` - Analyze test files for screenshot opportunities
+- Framework-specific code examples
+- Respect your test structure and patterns
+
+### ⚡ **Quick Setup**
+- `/vizzly:setup` - Initialize Vizzly configuration
+- Environment variable guidance
+- CI/CD integration help
+
+## MCP Server Tools
+
+The plugin provides an MCP server with direct access to Vizzly data:
+
+### Local TDD Tools
+- `detect_context` - Detect if using local TDD or cloud mode
+- `get_tdd_status` - Get current TDD comparison results
+- `read_comparison_details` - Detailed info for specific screenshot
+- `accept_baseline` - Accept a screenshot as new baseline
+- `reject_baseline` - Reject a baseline with reason
+
+### Cloud API Tools
+- `list_recent_builds` - List recent builds with filtering
+- `get_build_status` - Get build status with commit context
+- `get_comparison` - Get comparison details with screenshots
+- `approve_comparison` - Approve a comparison with comment
+- `reject_comparison` - Reject a comparison with reason
+- `create_build_comment` - Add comment to build
+
+## Authentication
+
+The plugin automatically uses your Vizzly authentication with the following priority:
+
+1. **Explicitly provided token** (via tool parameters)
+2. **Environment variable** (`VIZZLY_TOKEN`)
+3. **Project mapping** (configured via `vizzly project:select`)
+4. **User access token** (from `vizzly login`)
+
+### Getting Started
+
+**For local development:**
+```bash
+vizzly login                # Authenticate with your Vizzly account
+vizzly project:select       # Optional: set project-specific token
+```
+
+**For CI/CD:**
+```bash
+export VIZZLY_TOKEN=vzt_your_project_token
+```
+
+The plugin will automatically use the appropriate token based on your context.
+
+## Requirements
+
+- Claude Code
+- Node.js 20+
+- Vizzly CLI (`@vizzly-testing/cli`) installed in your project
+- TDD mode running for local features
+- Authentication configured (see above) for cloud features
+
+## Documentation
+
+- [Vizzly CLI](https://github.com/vizzly-testing/vizzly-cli) - Official CLI documentation
+- [Vizzly Platform](https://vizzly.dev) - Web dashboard and cloud features
+- [Claude Code](https://claude.com/claude-code) - Claude Code documentation
+
+## License
+
+MIT © Vizzly Team

package/claude-plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,28 @@
+{
+  "name": "vizzly-marketplace",
+  "owner": {
+    "name": "Vizzly Team",
+    "email": "team@vizzly.dev"
+  },
+  "metadata": {
+    "description": "Official Vizzly plugin for Claude Code - visual regression testing integration with TDD workflow support",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "vizzly",
+      "source": "./",
+      "description": "Visual regression testing integration for Vizzly - TDD workflow support and debugging tools",
+      "version": "0.1.0",
+      "author": {
+        "name": "Vizzly Team",
+        "url": "https://vizzly.dev"
+      },
+      "homepage": "https://vizzly.dev",
+      "repository": "https://github.com/vizzly-testing/vizzly-cli",
+      "license": "MIT",
+      "keywords": ["visual-testing", "regression-testing", "tdd", "screenshot-testing", "vizzly"],
+      "category": "testing"
+    }
+  ]
+}

package/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "vizzly",
+  "version": "0.1.0",
+  "description": "Visual regression testing integration for Vizzly - TDD workflow support and debugging tools",
+  "author": {
+    "name": "Vizzly Team",
+    "url": "https://vizzly.dev"
+  },
+  "homepage": "https://vizzly.dev",
+  "repository": "https://github.com/vizzly-testing/cli",
+  "license": "MIT",
+  "keywords": ["visual-testing", "regression-testing", "tdd", "screenshot-testing", "vizzly"],
+  "mcpServers": "./.mcp.json"
+}

package/claude-plugin/commands/debug-diff.md

@@ -0,0 +1,153 @@
+---
+description: Analyze a specific visual regression failure and suggest fixes
+---
+
+# Debug Vizzly Visual Regression
+
+Analyze a specific failing visual comparison in detail. Supports both local TDD mode and cloud API mode.
+
+## Process
+
+1. **Call the unified MCP tool**: Use `read_comparison_details` with the identifier (screenshot name or comparison ID)
+   - The tool automatically detects whether to use local TDD mode or cloud mode
+   - Pass screenshot name (e.g., "homepage_desktop") for local mode
+   - Pass comparison ID (e.g., "cmp_abc123") for cloud mode
+   - Returns a response with `mode` field indicating which mode was used
+
+2. **Check the mode in the response**:
+   - **Local mode** (`mode: "local"`): Returns filesystem paths (`baselinePath`, `currentPath`, `diffPath`)
+   - **Cloud mode** (`mode: "cloud"`): Returns URLs (`baselineUrl`, `currentUrl`, `diffUrl`)
+
+3. **Analyze the comparison data**:
+   - Diff percentage and threshold
+   - Status (failed/new/passed)
+   - Image references (paths or URLs depending on mode)
+
+4. **View the actual images** (critical for visual analysis):
+
+   Check the `mode` field in the response to determine which tool to use:
+
+   **If mode is "local":**
+   - Response contains filesystem paths (`baselinePath`, `currentPath`, `diffPath`)
+   - **Use the Read tool to view ONLY baselinePath and currentPath**
+   - **DO NOT read diffPath** - it causes API errors
+
+   **If mode is "cloud":**
+   - Response contains public URLs (`baselineUrl`, `currentUrl`, `diffUrl`)
+   - **Use the WebFetch tool to view ONLY baselineUrl and currentUrl**
+   - **DO NOT fetch diffUrl** - it causes API errors
+
+   **IMPORTANT:** You MUST view the baseline and current images to provide accurate analysis
+
+5. **Provide detailed visual insights** based on what you see:
+   - What type of change was detected (small/moderate/large diff)
+   - Describe the specific visual differences you observe in the images
+   - Identify which UI components, elements, or layouts changed
+   - Possible causes based on diff percentage and visual inspection:
+     - <1%: Anti-aliasing, font rendering, subpixel differences
+     - 1-5%: Layout shifts, padding/margin changes, color variations
+     - > 5%: Significant layout changes, missing content, major visual updates
+
+6. **Suggest next steps** based on the mode:
+   - **If local mode**: Whether to accept using `accept_baseline` tool
+   - **If cloud mode**: Whether to approve/reject using `approve_comparison` or `reject_comparison` tools
+   - Areas to investigate if unintentional
+   - How to fix common issues
+   - Specific code changes if you can identify them from the visual diff
+
+## Example Analysis (Local TDD Mode)
+
+```
+Step 1: Call read_comparison_details with screenshot name
+Tool: read_comparison_details({ identifier: "homepage" })
+
+Response:
+{
+  "name": "homepage",
+  "status": "failed",
+  "diffPercentage": 2.3,
+  "threshold": 0.1,
+  "mode": "local",
+  "baselinePath": "/Users/you/project/.vizzly/baselines/homepage.png",
+  "currentPath": "/Users/you/project/.vizzly/screenshots/homepage.png",
+  "diffPath": "/Users/you/project/.vizzly/diffs/homepage.png"
+}
+
+Step 2: Detected mode is "local", so use Read tool for images
+Read(baselinePath) and Read(currentPath)
+
+Visual Analysis:
+[After reading the baseline and current image files...]
+
+Comparing the two images, the navigation header has shifted down by approximately 10-15 pixels.
+Specific changes observed:
+- The logo position moved from y:20px to y:35px
+- Navigation menu items are now overlapping with the hero section
+- The "Sign Up" button background changed from blue (#2563eb) to a darker blue (#1e40af)
+
+Root Cause:
+Based on the visual comparison, this appears to be a margin or padding change on the
+header element. The button color change is likely a hover state being captured.
+
+Recommendations:
+1. Check for recent CSS changes to:
+   - `.header` or `nav` margin-top/padding-top
+   - Any global layout shifts affecting the header
+2. The button color change suggests a hover state - ensure consistent state during screenshot capture
+3. If the header position change is intentional:
+   - Accept as new baseline using `accept_baseline` tool
+4. If unintentional:
+   - Revert CSS changes to header positioning
+   - Verify with: `git diff src/styles/header.css`
+```
+
+## Example Analysis (Cloud Mode)
+
+```
+Step 1: Call read_comparison_details with comparison ID
+Tool: read_comparison_details({
+  identifier: "cmp_xyz789",
+  apiToken: "vzt_..."
+})
+
+Response:
+{
+  "name": "homepage",
+  "status": "failed",
+  "diffPercentage": 2.3,
+  "threshold": 0.1,
+  "mode": "cloud",
+  "baselineUrl": "https://app.vizzly.dev/screenshots/abc123/baseline.png",
+  "currentUrl": "https://app.vizzly.dev/screenshots/abc123/current.png",
+  "diffUrl": "https://app.vizzly.dev/screenshots/abc123/diff.png",
+  "comparisonId": "cmp_xyz789",
+  "buildId": "bld_abc123"
+}
+
+Step 2: Detected mode is "cloud", so use WebFetch tool for images
+WebFetch(baselineUrl) and WebFetch(currentUrl)
+
+Visual Analysis:
+[After fetching the baseline and current image URLs...]
+
+[Same analysis as local mode example...]
+
+Recommendations:
+1. [Same technical recommendations as local mode...]
+2. If the header position change is intentional:
+   - Approve this comparison using `approve_comparison` tool
+3. If unintentional:
+   - Reject using `reject_comparison` tool with detailed reason
+   - Have the team fix the CSS changes
+```
+
+## Important Notes
+
+- **Unified Tool**: Always use `read_comparison_details` with the identifier - it automatically detects the mode
+- **Mode Detection**: Check the `mode` field in the response to know which viewing tool to use
+- **Image Viewing**:
+  - Local mode → Use Read tool with filesystem paths
+  - Cloud mode → Use WebFetch tool with URLs
+- **Diff Images**: NEVER attempt to view/read/fetch the diff image - it causes API errors
+- **Visual Analysis**: Always view the baseline and current images before providing analysis
+- Visual inspection reveals details that diff percentages alone cannot convey

package/claude-plugin/commands/setup.md

@@ -0,0 +1,137 @@
+---
+description: Initialize Vizzly visual testing in a project
+---
+
+# Setup Vizzly in Project
+
+Help the user set up Vizzly visual regression testing in their project.
+
+## Setup Steps
+
+**Execute steps 1-5 to complete the CLI setup, then proceed to step 6 for SDK recommendations.**
+
+1. **Check if Vizzly is already configured**
+   - Look for `vizzly.config.js` in the project root
+   - Check if `@vizzly-testing/cli` is in package.json
+   - If already configured, inform the user and exit
+
+2. **Install Vizzly CLI**
+
+   Run this command:
+
+   ```bash
+   npm install --save-dev @vizzly-testing/cli
+   ```
+
+3. **Initialize configuration**
+
+   Run this command:
+
+   ```bash
+   npx vizzly init
+   ```
+
+   This creates `vizzly.config.js` with sensible defaults.
+
+4. **Add .vizzly/ to .gitignore**
+
+   Add `.vizzly/` to the project's `.gitignore` file to avoid committing local TDD artifacts.
+
+5. **Environment Variables**
+
+   Present the user with instructions to set up their API token:
+
+   **For local development:**
+   Create a `.env` file:
+
+   ```
+   VIZZLY_TOKEN=your-api-token-here
+   ```
+
+   Add `.env` to `.gitignore`
+
+   **For CI/CD:**
+   Add `VIZZLY_TOKEN` as a secret in their CI provider
+
+6. **Next Steps**
+
+   After CLI setup is complete, detect the project type and recommend the appropriate SDK:
+
+   **SDK Detection Priority (check in this order):**
+   - **Ruby**: Check for `Gemfile` → Recommend Ruby SDK
+   - **Storybook**: Check for `@storybook/*` in package.json or `.storybook/` directory → Recommend Storybook SDK
+   - **Static Site**: Check for static site generators (`astro`, `next`, `gatsby`, `vitepress`, `eleventy` in package.json) or build directories (`dist/`, `build/`, `.next/out/`, `_site/`) → Recommend Static Site SDK
+   - **JavaScript/Node.js**: Check for `package.json` → Recommend JavaScript SDK
+
+   **Present the detected SDK recommendation:**
+
+   For Ruby:
+
+   ```
+   📦 Next: Install the Ruby SDK
+   gem install vizzly
+
+   Documentation: https://docs.vizzly.dev/integration/sdk/ruby/overview
+   ```
+
+   For Storybook:
+
+   ```
+   📦 Next: Install the Storybook SDK
+   npm install --save-dev @vizzly-testing/storybook
+
+   Documentation: https://docs.vizzly.dev/integration/sdk/storybook/overview
+   ```
+
+   For Static Site:
+
+   ```
+   📦 Next: Install the Static Site SDK
+   npm install --save-dev @vizzly-testing/static-site
+
+   Documentation: https://docs.vizzly.dev/integration/sdk/static-site/overview
+   ```
+
+   For JavaScript:
+
+   ```
+   📦 Next: Use the JavaScript SDK (already included with the CLI)
+
+   Documentation: https://docs.vizzly.dev/integration/sdk/javascript/overview
+   ```
+
+   **End with this context summary:**
+
+   ```
+   ✅ Setup Complete
+
+   What was accomplished:
+   - Vizzly CLI installed
+   - Configuration file created (vizzly.config.js)
+   - .vizzly/ added to .gitignore
+   - Environment variable instructions provided
+
+   What's next:
+   - Install the recommended SDK (see above)
+   - Add screenshot capture to your tests (if needed)
+   - Run `vizzly tdd start` to test locally
+
+   [For Claude: The CLI is now installed and configured. When the user returns saying they installed the SDK, help them integrate it into their tests and start capturing screenshots. The workflow is: install SDK → add screenshot calls to tests → run vizzly tdd to verify locally.]
+   ```
+
+## What NOT to Do
+
+- Do not modify their test files
+- Do not generate example test code
+- Do not make assumptions about their test framework
+- Do not create new test files
+
+## What to Provide
+
+- Installation commands
+- Configuration file creation
+- Environment setup guidance
+- Links to documentation
+- Next steps for integration
+
+Let the user integrate Vizzly into their existing tests themselves. Vizzly works with any test framework that can capture screenshots.