@vizzly-testing/cli 0.11.0 → 0.11.2

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

@@ -0,0 +1,266 @@
+# 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
+```
+
+## Migration Guide (v0.0.x → v0.1.0)
+
+**⚠️ Breaking Changes:** Slash commands for status checking and debugging have been replaced with Agent Skills.
+
+### What Changed
+
+**Before (v0.0.x):**
+```bash
+# Manually invoke slash commands
+/vizzly:tdd-status
+/vizzly:debug-diff homepage
+```
+
+**After (v0.1.0):**
+```bash
+# Just ask naturally - Skills activate automatically
+"How are my visual tests?"
+"The homepage screenshot is failing"
+```
+
+### Command Migration
+
+| Old Slash Command | New Approach | How It Works |
+|-------------------|--------------|--------------|
+| `/vizzly:tdd-status` | Ask: "How are my tests?" | `check-visual-tests` Skill activates automatically |
+| `/vizzly:debug-diff <name>` | Say: "Debug the homepage screenshot" | `debug-visual-regression` Skill activates automatically |
+| `/vizzly:setup` | Still `/vizzly:setup` | ✅ No change - explicit setup workflow |
+| `/vizzly:suggest-screenshots` | Still `/vizzly:suggest-screenshots` | ✅ No change - explicit suggestions workflow |
+
+### Why This Change?
+
+**Better UX:**
+- No need to memorize command syntax
+- Just describe what you need in natural language
+- Claude understands your intent and activates the right Skill
+- More intuitive and conversational workflow
+
+**What Are Agent Skills?**
+
+Agent Skills are model-invoked capabilities that Claude uses autonomously based on your request. Instead of explicitly typing `/command`, you simply ask questions or describe problems, and Claude will automatically use the appropriate Skill.
+
+**Still Prefer Explicit Commands?**
+
+You can still be explicit in your requests:
+- "Check my Vizzly test status" → Activates `check-visual-tests` Skill
+- "Debug the login screenshot failure" → Activates `debug-visual-regression` Skill
+
+The Skills will activate based on your intent, not rigid command syntax.
+
+## Features
+
+### ✨ **Agent Skills** (Model-Invoked)
+
+Claude automatically uses these Skills when you mention visual testing:
+
+**🐛 Debug Visual Regression**
+- Activated when you mention failing visual tests or screenshot differences
+- Automatically analyzes visual changes, identifies root causes
+- Compares baseline vs current screenshots
+- Suggests whether to accept or fix changes
+- Works with both local TDD and cloud modes
+
+**🔍 Check Visual Test Status**
+- Activated when you ask about test status or results
+- Provides quick summary of passed/failed/new screenshots
+- Shows diff percentages and threshold information
+- Links to dashboard for detailed review
+
+**Example usage:**
+- Just say: *"The homepage screenshot is failing"* → Claude debugs it
+- Just ask: *"How are my visual tests?"* → Claude checks status
+- No slash commands needed—Claude activates Skills automatically!
+
+### 📋 **Slash Commands** (User-Invoked)
+
+Explicit workflows you trigger manually:
+
+**⚡ Quick Setup**
+- `/vizzly:setup` - Initialize Vizzly configuration
+- Environment variable guidance
+- CI/CD integration help
+
+**💡 Screenshot Suggestions**
+- `/vizzly:suggest-screenshots` - Analyze test files for screenshot opportunities
+- Framework-specific code examples
+- Respect your test structure and patterns
+
+### Skills vs Slash Commands
+
+**Skills** are capabilities Claude uses autonomously based on your request. Just describe what you need naturally, and Claude will use the appropriate Skill.
+
+**Slash Commands** are explicit workflows you invoke manually when you want step-by-step guidance through a process.
+
+## 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
+
+## How It Works
+
+### Agent Skills
+
+The plugin's Skills use Claude Code's `allowed-tools` feature to restrict what actions they can perform:
+
+**Check Visual Test Status Skill:**
+- Can use: `get_tdd_status`, `detect_context`
+- Purpose: Quickly check test status without modifying anything
+
+**Debug Visual Regression Skill:**
+- Can use: `Read`, `WebFetch`, `read_comparison_details`, `accept_baseline`, `approve_comparison`, `reject_comparison`
+- Purpose: Analyze failures and suggest/apply fixes
+
+### MCP Server Integration
+
+The plugin bundles an MCP server that provides 15 tools for interacting with Vizzly:
+
+- **Automatic startup** - MCP server starts when plugin is enabled
+- **Token resolution** - Automatically finds your authentication token
+- **Dual mode** - Works with both local TDD and cloud builds
+- **No configuration needed** - Just install and use
+
+## Troubleshooting
+
+### Skills not activating
+
+If Claude isn't using the Skills automatically:
+
+1. Verify plugin is enabled: `/plugin`
+2. Check MCP server status: `/mcp` (should show `plugin:vizzly:vizzly`)
+3. Try being more explicit: "Check my Vizzly test status"
+
+### MCP server not connecting
+
+If the MCP server shows as "failed" in `/mcp`:
+
+1. Check Node.js version: `node --version` (requires 20+)
+2. View logs: `claude --debug`
+3. Reinstall plugin: `/plugin uninstall vizzly@vizzly-marketplace` then `/plugin install vizzly@vizzly-marketplace`
+
+### TDD server not found
+
+If Skills report "TDD server not running":
+
+1. Start TDD mode: `vizzly tdd start`
+2. Verify server is running: Check for `.vizzly/server.json`
+3. Run tests to generate screenshots
+
+## Example Workflows
+
+### Local TDD Development
+
+```bash
+# Start TDD server
+vizzly tdd start
+
+# Run your tests
+npm test
+
+# Ask Claude to check status
+# "How are my visual tests?"
+
+# If failures, ask Claude to debug
+# "The login page screenshot is failing"
+```
+
+### Cloud Build Review
+
+```bash
+# After CI/CD runs and creates a build
+# "Show me recent Vizzly builds"
+
+# Review specific comparison
+# "Analyze comparison cmp_abc123"
+
+# Approve or reject
+# Claude will suggest using approve/reject tools
+```
+
+## 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
+- [Agent Skills](https://docs.claude.com/en/docs/claude-code/skills) - Learn about Claude Code Skills
+
+## License
+
+MIT © Vizzly Team

package/claude-plugin/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to the Vizzly Claude Code plugin will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-10-18
+
+### Added
+- ✨ **Agent Skills** - Model-invoked capabilities that activate autonomously
+  - `check-visual-tests` Skill - Automatically checks test status when you ask about tests
+  - `debug-visual-regression` Skill - Automatically analyzes failures when you mention visual issues
+- 📦 MCP server configuration moved to plugin root (`.mcp.json`)
+- 📝 Comprehensive README with Skills documentation, troubleshooting, and workflows
+- 🔒 Tool restrictions via `allowed-tools` for better security and focused capabilities
+
+### Changed
+- 🔧 MCP server name: `vizzly-server` → `vizzly` (cleaner naming)
+- 🔧 Skills use correct tool prefix: `mcp__plugin_vizzly_vizzly__*`
+
+### Removed
+- ❌ **BREAKING:** `/vizzly:tdd-status` slash command → Replaced by `check-visual-tests` Skill
+- ❌ **BREAKING:** `/vizzly:debug-diff` slash command → Replaced by `debug-visual-regression` Skill
+
+### Migration Guide
+
+**Before (v0.0.x):**
+```bash
+# Manually invoke slash commands
+/vizzly:tdd-status
+/vizzly:debug-diff homepage
+```
+
+**After (v0.1.0):**
+```bash
+# Just ask naturally - Skills activate automatically
+"How are my visual tests?"
+"The homepage screenshot is failing"
+```
+
+**What Changed:**
+- **Status checks** are now autonomous - just ask about your tests
+- **Debugging** happens automatically when you mention failures
+- **No need to remember slash commands** - Claude understands your intent
+- **Setup and suggestions** still use slash commands (`/vizzly:setup`, `/vizzly:suggest-screenshots`)
+
+**Why This Change:**
+Agent Skills provide a more natural, intuitive experience. Instead of memorizing command syntax, you can ask questions in plain language and Claude will automatically use the right tools.
+
+**If You Prefer Explicit Commands:**
+While the slash commands are removed, you can still be explicit in your requests:
+- "Check my Vizzly test status" → Activates `check-visual-tests` Skill
+- "Debug the homepage screenshot" → Activates `debug-visual-regression` Skill
+
+### Fixed
+- MCP server location now follows Claude Code plugin specifications
+- Tool naming consistency across Skills and MCP server

package/{.claude-plugin → claude-plugin}/mcp/vizzly-server/cloud-api-provider.js

@@ -145,6 +145,35 @@ export class CloudAPIProvider {
     return data.comparison;
   }
 
+  /**
+   * Search for comparisons by name across builds
+   */
+  async searchComparisons(name, apiToken, options = {}) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('name is required and must be a non-empty string');
+    }
+
+    let { branch, limit = 50, offset = 0, apiUrl } = options;
+
+    let queryParams = new URLSearchParams({
+      name,
+      limit: limit.toString(),
+      offset: offset.toString()
+    });
+
+    if (branch) {
+      queryParams.append('branch', branch);
+    }
+
+    let data = await this.makeRequest(
+      `/api/sdk/comparisons/search?${queryParams}`,
+      apiToken,
+      apiUrl
+    );
+
+    return data;
+  }
+
   // ==================================================================
   // BUILD COMMENTS
   // ==================================================================

package/{.claude-plugin → claude-plugin}/mcp/vizzly-server/index.js

@@ -21,7 +21,7 @@ class VizzlyMCPServer {
   constructor() {
     this.server = new Server(
       {
-        name: 'vizzly-server',
+        name: 'vizzly',
         version: '0.1.0'
       },
       {
@@ -247,6 +247,41 @@ class VizzlyMCPServer {
             required: ['comparisonId']
           }
         },
+        {
+          name: 'search_comparisons',
+          description:
+            'Search for comparisons by screenshot name across recent builds in the cloud. Returns matching comparisons with their build context and screenshot URLs. Use this to find all instances of a specific screenshot across different builds for debugging.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              name: {
+                type: 'string',
+                description: 'Screenshot/comparison name to search for (supports partial matching)'
+              },
+              branch: {
+                type: 'string',
+                description: 'Optional branch name to filter results'
+              },
+              limit: {
+                type: 'number',
+                description: 'Maximum number of results to return (default: 50)'
+              },
+              offset: {
+                type: 'number',
+                description: 'Offset for pagination (default: 0)'
+              },
+              apiToken: {
+                type: 'string',
+                description: 'Vizzly API token (optional, auto-resolves from user login or env)'
+              },
+              apiUrl: {
+                type: 'string',
+                description: 'API base URL (optional)'
+              }
+            },
+            required: ['name']
+          }
+        },
         {
           name: 'create_build_comment',
           description: 'Create a comment on a build for collaboration',
@@ -668,6 +703,24 @@ class VizzlyMCPServer {
             };
           }
 
+          case 'search_comparisons': {
+            let apiToken = await this.resolveApiToken(args);
+            let results = await this.cloudProvider.searchComparisons(args.name, apiToken, {
+              branch: args.branch,
+              limit: args.limit,
+              offset: args.offset,
+              apiUrl: args.apiUrl
+            });
+            return {
+              content: [
+                {
+                  type: 'text',
+                  text: JSON.stringify(results, null, 2)
+                }
+              ]
+            };
+          }
+
           case 'create_build_comment': {
             let apiToken = await this.resolveApiToken(args);
             let result = await this.cloudProvider.createBuildComment(

package/claude-plugin/skills/check-visual-tests/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: Check Visual Test Status
+description: Check the status of Vizzly visual regression tests. Use when the user asks about test status, test results, what's failing, how tests are doing, or wants a summary of visual tests. Works with both local TDD and cloud modes.
+allowed-tools: mcp__plugin_vizzly_vizzly__get_tdd_status, mcp__plugin_vizzly_vizzly__detect_context
+---
+
+# Check Visual Test Status
+
+Automatically check Vizzly visual test status when the user asks about their tests. Provides a quick summary of passed, failed, and new screenshots.
+
+## When to Use This Skill
+
+Activate this Skill when the user:
+- Asks "How are my tests doing?"
+- Asks "Are there any failing tests?"
+- Asks "What's the status of visual tests?"
+- Asks "Show me test results"
+- Asks "What's failing?"
+- Wants a summary of visual regression tests
+
+## How This Skill Works
+
+1. **Detect context** (local TDD or cloud mode)
+2. **Fetch TDD status** from the local server
+3. **Analyze results** to identify failures, new screenshots, and passes
+4. **Provide summary** with actionable information
+5. **Link to dashboard** for detailed review
+
+## Instructions
+
+### Step 1: Get TDD Status
+
+Use the `get_tdd_status` tool from the Vizzly MCP server to fetch current comparison results.
+
+This returns:
+- Total screenshot count
+- Passed, failed, and new screenshot counts
+- List of all comparisons with details
+- Dashboard URL (if TDD server is running)
+
+### Step 2: Analyze the Results
+
+Examine the comparison data:
+- Count total, passed, failed, and new screenshots
+- Identify which specific screenshots failed
+- Note diff percentages for failures
+- Check if new screenshots need baselines
+
+### Step 3: Provide Clear Summary
+
+Format the output to be scannable and actionable:
+
+```
+Vizzly TDD Status:
+✅ Total: [count] screenshots
+✅ Passed: [count]
+❌ Failed: [count] (exceeded threshold)
+🆕 New: [count] (no baseline)
+
+Failed Comparisons:
+- [name] ([diff]% diff) - Exceeds [threshold]% threshold
+- [name] ([diff]% diff) - Exceeds [threshold]% threshold
+
+New Screenshots:
+- [name] (no baseline for comparison)
+
+Dashboard: http://localhost:47392
+```
+
+### Step 4: Suggest Next Steps
+
+Based on the results, provide guidance:
+
+**If there are failures:**
+- Suggest using the debug-visual-regression Skill for detailed analysis
+- Provide dashboard link for visual review
+- Mention accept/reject options
+
+**If there are new screenshots:**
+- Explain that new screenshots need baseline approval
+- Show how to accept them from dashboard or CLI
+
+**If all passed:**
+- Confirm tests are passing
+- No action needed
+
+## Example Output
+
+```
+User: "How are my tests?"
+
+Vizzly TDD Status:
+✅ Total: 15 screenshots
+✅ Passed: 12
+❌ Failed: 2 (exceeded threshold)
+🆕 New: 1 (no baseline)
+
+Failed Comparisons:
+- homepage (2.3% diff) - Exceeds 0.1% threshold
+  Check .vizzly/diffs/homepage.png
+- login-form (1.8% diff) - Exceeds 0.1% threshold
+  Check .vizzly/diffs/login-form.png
+
+New Screenshots:
+- dashboard (no baseline for comparison)
+
+Dashboard: http://localhost:47392
+
+Next Steps:
+- Review diff images to understand what changed
+- Accept baselines from dashboard if changes are intentional
+- For detailed analysis of failures, ask me to debug specific screenshots
+- Fix visual issues if changes are unintentional
+```
+
+## Example When All Pass
+
+```
+User: "Are my visual tests passing?"
+
+Vizzly TDD Status:
+✅ Total: 15 screenshots
+✅ All passed!
+
+No visual regressions detected. All screenshots match their baselines.
+
+Dashboard: http://localhost:47392
+```
+
+## Example When TDD Not Running
+
+```
+User: "How are my tests?"
+
+Vizzly TDD Status:
+❌ TDD server is not running
+
+To start TDD mode:
+  vizzly tdd start
+
+Then run your tests to capture screenshots.
+```
+
+## Important Notes
+
+- **Quick status check** - Designed for fast overview, not detailed analysis
+- **Use dashboard for visuals** - Link to dashboard for image review
+- **Suggest next steps** - Always provide actionable guidance
+- **Detect TDD mode** - Only works with local TDD server running
+- **For detailed debugging** - Suggest using debug-visual-regression Skill
+
+## Focus on Actionability
+
+Always end with clear next steps:
+- What to investigate
+- Which tools to use (dashboard, debug Skill)
+- How to accept/reject baselines
+- When to fix code vs accept changes