@vizzly-testing/cli 0.23.0 → 0.23.2

package/dist/utils/ci-env.js

@@ -4,6 +4,47 @@
  * Generic functions to extract git and PR information from any CI provider
  */
 
+import { readFileSync } from 'node:fs';
+
+// Cache for GitHub Actions event payload to avoid re-reading the file
+let _githubEventCache = null;
+
+/**
+ * Read and parse the GitHub Actions event payload from GITHUB_EVENT_PATH.
+ *
+ * GitHub Actions sets GITHUB_EVENT_PATH to a file containing the full webhook
+ * payload that triggered the workflow. This is essential for pull_request and
+ * pull_request_target events because GITHUB_SHA points to a merge commit,
+ * not the actual head commit.
+ *
+ * @returns {Object} Parsed event payload or empty object on failure
+ */
+export function getGitHubEvent() {
+  if (_githubEventCache !== null) {
+    return _githubEventCache;
+  }
+  let eventPath = process.env.GITHUB_EVENT_PATH;
+  if (!eventPath) {
+    _githubEventCache = {};
+    return _githubEventCache;
+  }
+  try {
+    let content = readFileSync(eventPath, 'utf8');
+    _githubEventCache = JSON.parse(content);
+  } catch {
+    // File doesn't exist or invalid JSON - fail silently with empty object
+    _githubEventCache = {};
+  }
+  return _githubEventCache;
+}
+
+/**
+ * Reset the GitHub event cache. Useful for testing.
+ */
+export function resetGitHubEventCache() {
+  _githubEventCache = null;
+}
+
 /**
  * Get the branch name from CI environment variables
  * @returns {string|null} Branch name or null if not available
@@ -45,15 +86,41 @@ export function getBranch() {
 }
 
 /**
- * Get the commit SHA from CI environment variables
+ * Get the commit SHA from CI environment variables.
+ *
+ * IMPORTANT: For GitHub Actions pull_request events, GITHUB_SHA points to a
+ * temporary merge commit, NOT the actual head commit of the PR. This function
+ * reads the event payload from GITHUB_EVENT_PATH to extract the correct SHA.
+ *
+ * See: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
+ * "GITHUB_SHA for this event is the last merge commit of the pull request merge branch.
+ * If you want to get the commit ID for the last commit to the head branch of the
+ * pull request, use github.event.pull_request.head.sha instead."
+ *
  * @returns {string|null} Commit SHA or null if not available
  */
 export function getCommit() {
-  return process.env.VIZZLY_COMMIT_SHA ||
-  // Vizzly override
-  process.env.GITHUB_SHA ||
-  // GitHub Actions
-  process.env.CI_COMMIT_SHA ||
+  // Vizzly override always takes priority
+  if (process.env.VIZZLY_COMMIT_SHA) {
+    return process.env.VIZZLY_COMMIT_SHA;
+  }
+
+  // GitHub Actions: extract the correct SHA based on event type
+  if (process.env.GITHUB_ACTIONS) {
+    let event = getGitHubEvent();
+
+    // For pull_request events, use the actual head commit SHA (not the merge commit)
+    // The event payload contains pull_request.head.sha which is what we want
+    if (event.pull_request?.head?.sha) {
+      return event.pull_request.head.sha;
+    }
+
+    // For push events or if event parsing failed, GITHUB_SHA is correct
+    return process.env.GITHUB_SHA || null;
+  }
+
+  // Other CI providers
+  return process.env.CI_COMMIT_SHA ||
   // GitLab CI
   process.env.CIRCLE_SHA1 ||
   // CircleCI
@@ -170,15 +237,30 @@ export function getPullRequestNumber() {
 }
 
 /**
- * Get the PR head SHA from CI environment variables
+ * Get the PR head SHA from CI environment variables.
+ *
+ * For GitHub Actions, this reads from the event payload to get the actual
+ * head commit SHA, not the merge commit that GITHUB_SHA points to.
+ *
  * @returns {string|null} PR head SHA or null if not available
  */
 export function getPullRequestHeadSha() {
-  return process.env.VIZZLY_PR_HEAD_SHA ||
-  // Vizzly override
-  process.env.GITHUB_SHA ||
-  // GitHub Actions
-  process.env.CI_COMMIT_SHA ||
+  // Vizzly override always takes priority
+  if (process.env.VIZZLY_PR_HEAD_SHA) {
+    return process.env.VIZZLY_PR_HEAD_SHA;
+  }
+
+  // GitHub Actions: extract from event payload for PRs
+  if (process.env.GITHUB_ACTIONS) {
+    let event = getGitHubEvent();
+    if (event.pull_request?.head?.sha) {
+      return event.pull_request.head.sha;
+    }
+    return process.env.GITHUB_SHA || null;
+  }
+
+  // Other CI providers
+  return process.env.CI_COMMIT_SHA ||
   // GitLab CI
   process.env.CIRCLE_SHA1 ||
   // CircleCI
@@ -200,13 +282,29 @@ export function getPullRequestHeadSha() {
 }
 
 /**
- * Get the PR base SHA from CI environment variables
+ * Get the PR base SHA from CI environment variables.
+ *
+ * For GitHub Actions, this reads from the event payload to get the base
+ * branch SHA that the PR is targeting.
+ *
  * @returns {string|null} PR base SHA or null if not available
  */
 export function getPullRequestBaseSha() {
-  return process.env.VIZZLY_PR_BASE_SHA ||
-  // Vizzly override
-  process.env.CI_MERGE_REQUEST_TARGET_BRANCH_SHA ||
+  // Vizzly override always takes priority
+  if (process.env.VIZZLY_PR_BASE_SHA) {
+    return process.env.VIZZLY_PR_BASE_SHA;
+  }
+
+  // GitHub Actions: extract from event payload
+  if (process.env.GITHUB_ACTIONS) {
+    let event = getGitHubEvent();
+    if (event.pull_request?.base?.sha) {
+      return event.pull_request.base.sha;
+    }
+  }
+
+  // Other CI providers
+  return process.env.CI_MERGE_REQUEST_TARGET_BRANCH_SHA ||
   // GitLab CI
   null // Most CIs don't provide this
   ;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.23.0",
+  "version": "0.23.2",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -51,7 +51,6 @@
   "files": [
     "bin",
     "dist",
-    "docs",
     "claude-plugin",
     "README.md",
     "LICENSE"

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