@vizzly-testing/cli 0.23.1 → 0.23.2

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

@@ -1,270 +0,0 @@
-# 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
-  - Parameters:
-    - `statusFilter` (optional): Filter by status - `'failed'`, `'new'`, `'passed'`, `'all'`, or `'summary'` (default)
-    - `limit` (optional): Maximum number of comparisons to return
-  - Default behavior (summary mode): Returns counts only without full comparison details for efficiency
-- `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/.claude-plugin/marketplace.json

@@ -1,28 +0,0 @@
-{
-  "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

@@ -1,14 +0,0 @@
-{
-  "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/.mcp.json

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

package/claude-plugin/CHANGELOG.md

@@ -1,85 +0,0 @@
-# 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).
-
-## [Unreleased]
-
-### Added
-- 📚 **New MCP Server:** `vizzly-docs` - Easy access to Vizzly documentation
-  - `list_docs` - Browse all docs with optional category filtering
-  - `get_doc` - Retrieve full markdown content for any doc page
-  - `search_docs` - Keyword search across titles, descriptions, and categories
-  - `get_sidebar` - View complete documentation navigation structure
-  - Fetches from live docs.vizzly.dev site with intelligent caching
-- ⚡️ **Performance:** `get_tdd_status` now supports filtering and pagination
-  - New `statusFilter` parameter: `'failed'`, `'new'`, `'passed'`, `'all'`, or `'summary'` (default)
-  - New `limit` parameter for capping number of comparisons returned
-  - Default behavior (summary mode) returns only counts for better token efficiency
-- 🔧 **API Enhancement:** Cloud API provider now includes approval status and flaky screenshot detection
-  - Added approval status breakdown (pending/approved/rejected/auto_approved)
-  - Added flaky screenshot count
-  - Added hot spot coverage metadata for quick triage
-
-### Changed
-- 🔧 **Internal:** `acceptBaseline()` in TDD service now accepts both comparison ID (string) or full comparison object
-  - Enables accepting baselines from report-data.json without in-memory lookup
-  - Fixes issue where accepting from dashboard wasn't working properly
-
-### Fixed
-- 🐛 Fixed path bug in local TDD provider: `screenshots/` → `current/` directory
-- 🐛 Fixed API field mapping in cloud provider: API returns `result` not `status`
-
-## [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/commands/setup.md

@@ -1,137 +0,0 @@
----
-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.

package/claude-plugin/commands/suggest-screenshots.md

@@ -1,111 +0,0 @@
----
-description: Analyze test files and suggest where visual screenshots would be valuable
----
-
-# Suggest Screenshot Opportunities
-
-Analyze existing test files to identify ideal locations for visual regression testing.
-
-## Process
-
-1. **Detect SDK type** (same logic as setup command)
-
-   **If Storybook detected** (`@storybook/*` in package.json or `.storybook/` directory):
-   - Inform user that Storybook SDK auto-discovers all stories
-   - No manual screenshot calls needed
-   - Exit early
-
-   **If Static Site detected** (build directories like `dist/`, `build/`, `.next/out/` or static site generators):
-   - Inform user that Static Site SDK auto-discovers all pages
-   - No manual screenshot calls needed
-   - Exit early
-
-   **Otherwise continue** with test file analysis below.
-
-2. **Ask user for test directory** if not obvious (e.g., `tests/`, `e2e/`, `__tests__/`, `spec/`)
-
-3. **Find test files** using glob patterns:
-   - `**/*.test.{js,ts,jsx,tsx}`
-   - `**/*.spec.{js,ts,jsx,tsx}`
-   - `**/e2e/**/*.{js,ts}`
-
-   **IMPORTANT: Exclude these directories:**
-   - `node_modules/`
-   - `dist/`, `build/`, `out/`
-   - `.next/`, `.nuxt/`, `.vite/`
-   - `coverage/`, `.nyc_output/`
-   - `vendor/`
-   - Any hidden directories (`.*/`)
-
-   Use the Glob tool with explicit exclusion or filter results to avoid these directories.
-
-4. **Analyze test files** looking for:
-   - Page navigations (`.goto()`, `.visit()`, `navigate()`)
-   - User interactions before assertions (`.click()`, `.type()`, `.fill()`)
-   - Component rendering (React Testing Library, etc.)
-   - Visual assertions or wait conditions
-
-5. **Suggest screenshot points** where:
-   - After page loads or navigations
-   - After key user interactions
-   - Before visual assertions
-   - At different viewport sizes
-   - For different user states (logged in/out, etc.)
-
-6. **Provide code examples** specific to their test framework:
-
-   **Playwright:**
-
-   ```javascript
-   import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
-
-   // After page navigation
-   await page.goto('/dashboard');
-   await vizzlyScreenshot('dashboard-logged-in', await page.screenshot(), {
-     browser: 'chrome',
-     viewport: '1920x1080'
-   });
-   ```
-
-   **Cypress:**
-
-   ```javascript
-   cy.visit('/login');
-   cy.screenshot('login-page');
-   // Then add vizzlyScreenshot in custom command
-   ```
-
-## Output Format
-
-```
-Found 8 potential screenshot opportunities in your tests:
-
-tests/e2e/auth.spec.js:
-  Line 15: After login page navigation
-    Suggested screenshot: 'login-page'
-    Reason: Page load after navigation
-
-  Line 28: After successful login
-    Suggested screenshot: 'dashboard-authenticated'
-    Reason: User state change (logged in)
-
-tests/e2e/checkout.spec.js:
-  Line 42: Shopping cart with items
-    Suggested screenshot: 'cart-with-items'
-    Reason: Visual state after user interaction
-
-  Line 67: Checkout confirmation page
-    Suggested screenshot: 'order-confirmation'
-    Reason: Final state of user flow
-
-Example integration for Playwright:
-[Provide code example specific to their test]
-```
-
-## Important Notes
-
-- **Do NOT modify test files**
-- **Do NOT create new test files**
-- Only provide suggestions and examples
-- Let the user decide where to add screenshots
-- Respect their test framework and structure