@vizzly-testing/cli 0.10.3 → 0.11.0

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/dist/cli.js

@@ -9,6 +9,10 @@ import { tddStartCommand, tddStopCommand, tddStatusCommand, runDaemonChild } fro
 import { statusCommand, validateStatusOptions } from './commands/status.js';
 import { finalizeCommand, validateFinalizeOptions } from './commands/finalize.js';
 import { doctorCommand, validateDoctorOptions } from './commands/doctor.js';
+import { loginCommand, validateLoginOptions } from './commands/login.js';
+import { logoutCommand, validateLogoutOptions } from './commands/logout.js';
+import { whoamiCommand, validateWhoamiOptions } from './commands/whoami.js';
+import { projectSelectCommand, projectListCommand, projectTokenCommand, projectRemoveCommand, validateProjectOptions } from './commands/project.js';
 import { getPackageVersion } from './utils/package-info.js';
 import { loadPlugins } from './plugin-loader.js';
 import { loadConfig } from './utils/config-loader.js';
@@ -194,4 +198,64 @@ program.command('doctor').description('Run diagnostics to check your environment
   }
   await doctorCommand(options, globalOptions);
 });
+program.command('login').description('Authenticate with your Vizzly account').option('--api-url <url>', 'API URL override').action(async options => {
+  const globalOptions = program.opts();
+
+  // Validate options
+  const validationErrors = validateLoginOptions(options);
+  if (validationErrors.length > 0) {
+    console.error('Validation errors:');
+    validationErrors.forEach(error => console.error(`  - ${error}`));
+    process.exit(1);
+  }
+  await loginCommand(options, globalOptions);
+});
+program.command('logout').description('Clear stored authentication tokens').option('--api-url <url>', 'API URL override').action(async options => {
+  const globalOptions = program.opts();
+
+  // Validate options
+  const validationErrors = validateLogoutOptions(options);
+  if (validationErrors.length > 0) {
+    console.error('Validation errors:');
+    validationErrors.forEach(error => console.error(`  - ${error}`));
+    process.exit(1);
+  }
+  await logoutCommand(options, globalOptions);
+});
+program.command('whoami').description('Show current authentication status and user information').option('--api-url <url>', 'API URL override').action(async options => {
+  const globalOptions = program.opts();
+
+  // Validate options
+  const validationErrors = validateWhoamiOptions(options);
+  if (validationErrors.length > 0) {
+    console.error('Validation errors:');
+    validationErrors.forEach(error => console.error(`  - ${error}`));
+    process.exit(1);
+  }
+  await whoamiCommand(options, globalOptions);
+});
+program.command('project:select').description('Configure project for current directory').option('--api-url <url>', 'API URL override').action(async options => {
+  const globalOptions = program.opts();
+
+  // Validate options
+  const validationErrors = validateProjectOptions(options);
+  if (validationErrors.length > 0) {
+    console.error('Validation errors:');
+    validationErrors.forEach(error => console.error(`  - ${error}`));
+    process.exit(1);
+  }
+  await projectSelectCommand(options, globalOptions);
+});
+program.command('project:list').description('Show all configured projects').action(async options => {
+  const globalOptions = program.opts();
+  await projectListCommand(options, globalOptions);
+});
+program.command('project:token').description('Show project token for current directory').action(async options => {
+  const globalOptions = program.opts();
+  await projectTokenCommand(options, globalOptions);
+});
+program.command('project:remove').description('Remove project configuration for current directory').action(async options => {
+  const globalOptions = program.opts();
+  await projectRemoveCommand(options, globalOptions);
+});
 program.parse();

package/dist/client/index.js

@@ -4,6 +4,7 @@
  */
 
 import { getServerUrl, getBuildId, isTddMode, setVizzlyEnabled } from '../utils/environment-config.js';
+import { resolveImageBuffer } from '../utils/file-helpers.js';
 import { existsSync, readFileSync } from 'fs';
 import { join, parse, dirname } from 'path';
 
@@ -184,7 +185,7 @@ function createSimpleClient(serverUrl) {
  * Take a screenshot for visual regression testing
  *
  * @param {string} name - Unique name for the screenshot
- * @param {Buffer} imageBuffer - PNG image data as a Buffer
+ * @param {Buffer|string} imageBuffer - PNG image data as a Buffer, or a file path to an image
  * @param {Object} [options] - Optional configuration
  * @param {Record<string, any>} [options.properties] - Additional properties to attach to the screenshot
  * @param {number} [options.threshold=0] - Pixel difference threshold (0-100)
@@ -193,13 +194,17 @@ function createSimpleClient(serverUrl) {
  * @returns {Promise<void>}
  *
  * @example
- * // Basic usage
+ * // Basic usage with Buffer
  * import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
  *
  * const screenshot = await page.screenshot();
  * await vizzlyScreenshot('homepage', screenshot);
  *
  * @example
+ * // Basic usage with file path
+ * await vizzlyScreenshot('homepage', './screenshots/homepage.png');
+ *
+ * @example
  * // With properties and threshold
  * await vizzlyScreenshot('checkout-form', screenshot, {
  *   properties: {
@@ -210,6 +215,8 @@ function createSimpleClient(serverUrl) {
  * });
  *
  * @throws {VizzlyError} When screenshot capture fails or client is not initialized
+ * @throws {VizzlyError} When file path is provided but file doesn't exist
+ * @throws {VizzlyError} When file cannot be read due to permissions or I/O errors
  */
 export async function vizzlyScreenshot(name, imageBuffer, options = {}) {
   if (isVizzlyDisabled()) {
@@ -224,7 +231,10 @@ export async function vizzlyScreenshot(name, imageBuffer, options = {}) {
     }
     return;
   }
-  return client.screenshot(name, imageBuffer, options);
+
+  // Resolve Buffer or file path using shared utility
+  const buffer = resolveImageBuffer(imageBuffer, 'screenshot');
+  return client.screenshot(name, buffer, options);
 }
 
 /**

package/dist/commands/login.js

@@ -0,0 +1,195 @@
+/**
+ * Login command implementation
+ * Authenticates user via OAuth device flow
+ */
+
+import { ConsoleUI } from '../utils/console-ui.js';
+import { AuthService } from '../services/auth-service.js';
+import { getApiUrl } from '../utils/environment-config.js';
+import { openBrowser } from '../utils/browser.js';
+
+/**
+ * Login command implementation using OAuth device flow
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function loginCommand(options = {}, globalOptions = {}) {
+  // Create UI handler
+  let ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    ui.info('Starting Vizzly authentication...');
+    console.log(''); // Empty line for spacing
+
+    // Create auth service
+    let authService = new AuthService({
+      baseUrl: options.apiUrl || getApiUrl()
+    });
+
+    // Initiate device flow
+    ui.startSpinner('Connecting to Vizzly...');
+    let deviceFlow = await authService.initiateDeviceFlow();
+    ui.stopSpinner();
+
+    // Handle both snake_case and camelCase field names
+    let verificationUri = deviceFlow.verification_uri || deviceFlow.verificationUri;
+    let userCode = deviceFlow.user_code || deviceFlow.userCode;
+    let deviceCode = deviceFlow.device_code || deviceFlow.deviceCode;
+    if (!verificationUri || !userCode || !deviceCode) {
+      throw new Error('Invalid device flow response from server');
+    }
+
+    // Build URL with pre-filled code
+    let urlWithCode = `${verificationUri}?code=${userCode}`;
+
+    // Display user code prominently
+    console.log(''); // Empty line for spacing
+    console.log('='.repeat(50));
+    console.log('');
+    console.log('  Please visit the following URL to authorize this device:');
+    console.log('');
+    console.log(`  ${urlWithCode}`);
+    console.log('');
+    console.log('  Your code (pre-filled):');
+    console.log('');
+    console.log(`  ${ui.colors.bold(ui.colors.cyan(userCode))}`);
+    console.log('');
+    console.log('='.repeat(50));
+    console.log(''); // Empty line for spacing
+
+    // Try to open browser with pre-filled code
+    let browserOpened = await openBrowser(urlWithCode);
+    if (browserOpened) {
+      ui.info('Opening browser...');
+    } else {
+      ui.warning('Could not open browser automatically. Please open the URL manually.');
+    }
+    console.log(''); // Empty line for spacing
+    ui.info('After authorizing in your browser, press Enter to continue...');
+
+    // Wait for user to press Enter
+    await new Promise(resolve => {
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.once('data', () => {
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        resolve();
+      });
+    });
+
+    // Check authorization status
+    ui.startSpinner('Checking authorization status...');
+    let pollResponse = await authService.pollDeviceAuthorization(deviceCode);
+    ui.stopSpinner();
+    let tokenData = null;
+
+    // Check if authorization was successful by looking for tokens
+    if (pollResponse.tokens && pollResponse.tokens.accessToken) {
+      // Success! We got tokens
+      tokenData = pollResponse;
+    } else if (pollResponse.status === 'pending') {
+      throw new Error('Authorization not complete yet. Please complete the authorization in your browser and try running "vizzly login" again.');
+    } else if (pollResponse.status === 'expired') {
+      throw new Error('Device code expired. Please try logging in again.');
+    } else if (pollResponse.status === 'denied') {
+      throw new Error('Authorization denied. Please try logging in again.');
+    } else {
+      throw new Error('Unexpected response from authorization server. Please try logging in again.');
+    }
+
+    // Complete device flow and save tokens
+    // Handle both snake_case and camelCase for token data, and nested tokens object
+    let tokensData = tokenData.tokens || tokenData;
+    let tokenExpiresIn = tokensData.expiresIn || tokensData.expires_in;
+    let tokenExpiresAt = tokenExpiresIn ? new Date(Date.now() + tokenExpiresIn * 1000).toISOString() : tokenData.expires_at || tokenData.expiresAt;
+    let tokens = {
+      accessToken: tokensData.accessToken || tokensData.access_token,
+      refreshToken: tokensData.refreshToken || tokensData.refresh_token,
+      expiresAt: tokenExpiresAt,
+      user: tokenData.user,
+      organizations: tokenData.organizations
+    };
+    await authService.completeDeviceFlow(tokens);
+
+    // Display success message
+    ui.success('Successfully authenticated!');
+    console.log(''); // Empty line for spacing
+
+    // Show user info
+    if (tokens.user) {
+      ui.info(`User: ${tokens.user.name || tokens.user.username}`);
+      ui.info(`Email: ${tokens.user.email}`);
+    }
+
+    // Show organization info
+    if (tokens.organizations && tokens.organizations.length > 0) {
+      console.log(''); // Empty line for spacing
+      ui.info('Organizations:');
+      for (let org of tokens.organizations) {
+        console.log(`  - ${org.name}${org.slug ? ` (@${org.slug})` : ''}`);
+      }
+    }
+
+    // Show token expiry info
+    if (tokens.expiresAt) {
+      console.log(''); // Empty line for spacing
+      let expiresAt = new Date(tokens.expiresAt);
+      let msUntilExpiry = expiresAt.getTime() - Date.now();
+      let daysUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60 * 60 * 24));
+      let hoursUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60 * 60));
+      let minutesUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60));
+      if (daysUntilExpiry > 0) {
+        ui.info(`Token expires in ${daysUntilExpiry} day${daysUntilExpiry !== 1 ? 's' : ''} (${expiresAt.toLocaleDateString()})`);
+      } else if (hoursUntilExpiry > 0) {
+        ui.info(`Token expires in ${hoursUntilExpiry} hour${hoursUntilExpiry !== 1 ? 's' : ''}`);
+      } else if (minutesUntilExpiry > 0) {
+        ui.info(`Token expires in ${minutesUntilExpiry} minute${minutesUntilExpiry !== 1 ? 's' : ''}`);
+      }
+    }
+    console.log(''); // Empty line for spacing
+    ui.info('You can now use Vizzly CLI commands without setting VIZZLY_TOKEN');
+    ui.cleanup();
+  } catch (error) {
+    ui.stopSpinner();
+
+    // Handle authentication errors with helpful messages
+    if (error.name === 'AuthError') {
+      ui.error('Authentication failed', error, 0);
+      console.log(''); // Empty line for spacing
+      console.log('Please try logging in again.');
+      console.log("If you don't have an account, sign up at https://vizzly.dev");
+      process.exit(1);
+    } else if (error.code === 'RATE_LIMIT_ERROR') {
+      ui.error('Too many login attempts', error, 0);
+      console.log(''); // Empty line for spacing
+      console.log('Please wait a few minutes before trying again.');
+      process.exit(1);
+    } else {
+      ui.error('Login failed', error, 0);
+      console.log(''); // Empty line for spacing
+      console.log('Error details:', error.message);
+      if (globalOptions.verbose && error.stack) {
+        console.error(''); // Empty line for spacing
+        console.error(error.stack);
+      }
+      process.exit(1);
+    }
+  }
+}
+
+/**
+ * Validate login options
+ * @param {Object} options - Command options
+ */
+export function validateLoginOptions() {
+  let errors = [];
+
+  // No specific validation needed for login command
+  // OAuth device flow handles everything via browser
+
+  return errors;
+}

package/dist/commands/logout.js

@@ -0,0 +1,71 @@
+/**
+ * Logout command implementation
+ * Clears stored authentication tokens
+ */
+
+import { ConsoleUI } from '../utils/console-ui.js';
+import { AuthService } from '../services/auth-service.js';
+import { getApiUrl } from '../utils/environment-config.js';
+import { getAuthTokens } from '../utils/global-config.js';
+
+/**
+ * Logout command implementation
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function logoutCommand(options = {}, globalOptions = {}) {
+  // Create UI handler
+  let ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    // Check if user is logged in
+    let auth = await getAuthTokens();
+    if (!auth || !auth.accessToken) {
+      ui.info('You are not logged in');
+      ui.cleanup();
+      return;
+    }
+
+    // Logout
+    ui.startSpinner('Logging out...');
+    let authService = new AuthService({
+      baseUrl: options.apiUrl || getApiUrl()
+    });
+    await authService.logout();
+    ui.stopSpinner();
+    ui.success('Successfully logged out');
+    if (globalOptions.json) {
+      ui.data({
+        loggedOut: true
+      });
+    } else {
+      console.log(''); // Empty line for spacing
+      ui.info('Your authentication tokens have been cleared');
+      ui.info('Run "vizzly login" to authenticate again');
+    }
+    ui.cleanup();
+  } catch (error) {
+    ui.stopSpinner();
+    ui.error('Logout failed', error, 0);
+    if (globalOptions.verbose && error.stack) {
+      console.error(''); // Empty line for spacing
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Validate logout options
+ * @param {Object} options - Command options
+ */
+export function validateLogoutOptions() {
+  let errors = [];
+
+  // No specific validation needed for logout command
+
+  return errors;
+}