@vizzly-testing/cli 0.10.3 → 0.11.1

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;
+}

package/dist/commands/project.js

@@ -0,0 +1,351 @@
+/**
+ * Project management commands
+ * Select, list, and manage project tokens
+ */
+
+import { ConsoleUI } from '../utils/console-ui.js';
+import { AuthService } from '../services/auth-service.js';
+import { getApiUrl } from '../utils/environment-config.js';
+import { getAuthTokens, saveProjectMapping, getProjectMapping, getProjectMappings, deleteProjectMapping } from '../utils/global-config.js';
+import { resolve } from 'path';
+import readline from 'readline';
+
+/**
+ * Project select command - configure project for current directory
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function projectSelectCommand(options = {}, globalOptions = {}) {
+  let ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    // Check authentication
+    let auth = await getAuthTokens();
+    if (!auth || !auth.accessToken) {
+      ui.error('Not authenticated', null, 0);
+      console.log(''); // Empty line for spacing
+      ui.info('Run "vizzly login" to authenticate first');
+      process.exit(1);
+    }
+    let authService = new AuthService({
+      baseUrl: options.apiUrl || getApiUrl()
+    });
+
+    // Get user info to show organizations
+    ui.startSpinner('Fetching organizations...');
+    let userInfo = await authService.whoami();
+    ui.stopSpinner();
+    if (!userInfo.organizations || userInfo.organizations.length === 0) {
+      ui.error('No organizations found', null, 0);
+      console.log(''); // Empty line for spacing
+      ui.info('Create an organization at https://vizzly.dev');
+      process.exit(1);
+    }
+
+    // Select organization
+    console.log(''); // Empty line for spacing
+    ui.info('Select an organization:');
+    console.log(''); // Empty line for spacing
+
+    userInfo.organizations.forEach((org, index) => {
+      console.log(`  ${index + 1}. ${org.name} (@${org.slug})`);
+    });
+    console.log(''); // Empty line for spacing
+    let orgChoice = await promptNumber('Enter number', 1, userInfo.organizations.length);
+    let selectedOrg = userInfo.organizations[orgChoice - 1];
+
+    // List projects for organization
+    ui.startSpinner(`Fetching projects for ${selectedOrg.name}...`);
+    let response = await makeAuthenticatedRequest(`${options.apiUrl || getApiUrl()}/api/project`, {
+      headers: {
+        Authorization: `Bearer ${auth.accessToken}`,
+        'X-Organization': selectedOrg.slug
+      }
+    });
+    ui.stopSpinner();
+
+    // Handle both array response and object with projects property
+    let projects = Array.isArray(response) ? response : response.projects || [];
+    if (projects.length === 0) {
+      ui.error('No projects found', null, 0);
+      console.log(''); // Empty line for spacing
+      ui.info(`Create a project in ${selectedOrg.name} at https://vizzly.dev`);
+      process.exit(1);
+    }
+
+    // Select project
+    console.log(''); // Empty line for spacing
+    ui.info('Select a project:');
+    console.log(''); // Empty line for spacing
+
+    projects.forEach((project, index) => {
+      console.log(`  ${index + 1}. ${project.name} (${project.slug})`);
+    });
+    console.log(''); // Empty line for spacing
+    let projectChoice = await promptNumber('Enter number', 1, projects.length);
+    let selectedProject = projects[projectChoice - 1];
+
+    // Create API token for project
+    ui.startSpinner(`Creating API token for ${selectedProject.name}...`);
+    let tokenResponse = await makeAuthenticatedRequest(`${options.apiUrl || getApiUrl()}/api/project/${selectedProject.slug}/tokens`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${auth.accessToken}`,
+        'X-Organization': selectedOrg.slug,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        name: `CLI Token - ${new Date().toLocaleDateString()}`,
+        description: `Generated by vizzly CLI for ${process.cwd()}`
+      })
+    });
+    ui.stopSpinner();
+
+    // Save project mapping
+    let currentDir = resolve(process.cwd());
+    await saveProjectMapping(currentDir, {
+      token: tokenResponse.token,
+      projectSlug: selectedProject.slug,
+      projectName: selectedProject.name,
+      organizationSlug: selectedOrg.slug
+    });
+    ui.success('Project configured!');
+    console.log(''); // Empty line for spacing
+    ui.info(`Project: ${selectedProject.name}`);
+    ui.info(`Organization: ${selectedOrg.name}`);
+    ui.info(`Directory: ${currentDir}`);
+    ui.cleanup();
+  } catch (error) {
+    ui.stopSpinner();
+    ui.error('Failed to configure project', error, 0);
+    if (globalOptions.verbose && error.stack) {
+      console.error(''); // Empty line for spacing
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Project list command - show all configured projects
+ * @param {Object} _options - Command options (unused)
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function projectListCommand(_options = {}, globalOptions = {}) {
+  let ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    let mappings = await getProjectMappings();
+    let paths = Object.keys(mappings);
+    if (paths.length === 0) {
+      ui.info('No projects configured');
+      console.log(''); // Empty line for spacing
+      ui.info('Run "vizzly project:select" to configure a project');
+      ui.cleanup();
+      return;
+    }
+    if (globalOptions.json) {
+      ui.data(mappings);
+      ui.cleanup();
+      return;
+    }
+    ui.info('Configured projects:');
+    console.log(''); // Empty line for spacing
+
+    let currentDir = resolve(process.cwd());
+    for (let path of paths) {
+      let mapping = mappings[path];
+      let isCurrent = path === currentDir;
+      let marker = isCurrent ? '→' : ' ';
+
+      // Extract token string (handle both string and object formats)
+      let tokenStr = typeof mapping.token === 'string' ? mapping.token : mapping.token?.token || '[invalid token]';
+      console.log(`${marker} ${path}`);
+      console.log(`  Project: ${mapping.projectName} (${mapping.projectSlug})`);
+      console.log(`  Organization: ${mapping.organizationSlug}`);
+      if (globalOptions.verbose) {
+        console.log(`  Token: ${tokenStr.substring(0, 20)}...`);
+        console.log(`  Created: ${new Date(mapping.createdAt).toLocaleString()}`);
+      }
+      console.log(''); // Empty line for spacing
+    }
+    ui.cleanup();
+  } catch (error) {
+    ui.error('Failed to list projects', error, 0);
+    if (globalOptions.verbose && error.stack) {
+      console.error(''); // Empty line for spacing
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Project token command - show/regenerate token for current directory
+ * @param {Object} _options - Command options (unused)
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function projectTokenCommand(_options = {}, globalOptions = {}) {
+  let ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    let currentDir = resolve(process.cwd());
+    let mapping = await getProjectMapping(currentDir);
+    if (!mapping) {
+      ui.error('No project configured for this directory', null, 0);
+      console.log(''); // Empty line for spacing
+      ui.info('Run "vizzly project:select" to configure a project');
+      process.exit(1);
+    }
+
+    // Extract token string (handle both string and object formats)
+    let tokenStr = typeof mapping.token === 'string' ? mapping.token : mapping.token?.token || '[invalid token]';
+    if (globalOptions.json) {
+      ui.data({
+        token: tokenStr,
+        projectSlug: mapping.projectSlug,
+        organizationSlug: mapping.organizationSlug
+      });
+      ui.cleanup();
+      return;
+    }
+    ui.info('Project token:');
+    console.log(''); // Empty line for spacing
+    console.log(`  ${tokenStr}`);
+    console.log(''); // Empty line for spacing
+    ui.info(`Project: ${mapping.projectName} (${mapping.projectSlug})`);
+    ui.info(`Organization: ${mapping.organizationSlug}`);
+    ui.cleanup();
+  } catch (error) {
+    ui.error('Failed to get project token', error, 0);
+    if (globalOptions.verbose && error.stack) {
+      console.error(''); // Empty line for spacing
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Helper to make authenticated API request
+ */
+async function makeAuthenticatedRequest(url, options = {}) {
+  let response = await fetch(url, options);
+  if (!response.ok) {
+    let errorText = '';
+    try {
+      let errorData = await response.json();
+      errorText = errorData.error || errorData.message || '';
+    } catch {
+      errorText = await response.text();
+    }
+    throw new Error(`API request failed: ${response.status}${errorText ? ` - ${errorText}` : ''}`);
+  }
+  return response.json();
+}
+
+/**
+ * Helper to prompt for a number
+ */
+function promptNumber(message, min, max) {
+  return new Promise(resolve => {
+    let rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    let ask = () => {
+      rl.question(`${message} (${min}-${max}): `, answer => {
+        let num = parseInt(answer, 10);
+        if (isNaN(num) || num < min || num > max) {
+          console.log(`Please enter a number between ${min} and ${max}`);
+          ask();
+        } else {
+          rl.close();
+          resolve(num);
+        }
+      });
+    };
+    ask();
+  });
+}
+
+/**
+ * Project remove command - remove project configuration for current directory
+ * @param {Object} _options - Command options (unused)
+ * @param {Object} globalOptions - Global CLI options
+ */
+export async function projectRemoveCommand(_options = {}, globalOptions = {}) {
+  let ui = new ConsoleUI({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    let currentDir = resolve(process.cwd());
+    let mapping = await getProjectMapping(currentDir);
+    if (!mapping) {
+      ui.info('No project configured for this directory');
+      ui.cleanup();
+      return;
+    }
+
+    // Confirm removal
+    console.log(''); // Empty line for spacing
+    ui.info('Current project configuration:');
+    console.log(`  Project: ${mapping.projectName} (${mapping.projectSlug})`);
+    console.log(`  Organization: ${mapping.organizationSlug}`);
+    console.log(`  Directory: ${currentDir}`);
+    console.log(''); // Empty line for spacing
+
+    let confirmed = await promptConfirm('Remove this project configuration?');
+    if (!confirmed) {
+      ui.info('Cancelled');
+      ui.cleanup();
+      return;
+    }
+    await deleteProjectMapping(currentDir);
+    ui.success('Project configuration removed');
+    console.log(''); // Empty line for spacing
+    ui.info('Run "vizzly project:select" to configure a different project');
+    ui.cleanup();
+  } catch (error) {
+    ui.error('Failed to remove project configuration', error, 0);
+    if (globalOptions.verbose && error.stack) {
+      console.error(''); // Empty line for spacing
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Helper to prompt for confirmation
+ */
+function promptConfirm(message) {
+  return new Promise(resolve => {
+    let rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question(`${message} (y/n): `, answer => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+/**
+ * Validate project command options
+ */
+export function validateProjectOptions() {
+  return [];
+}