@vizzly-testing/cli 0.10.3 → 0.11.1

package/dist/utils/file-helpers.js

@@ -0,0 +1,64 @@
+/**
+ * @module file-helpers
+ * @description Utilities for handling file-based screenshot inputs
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import { VizzlyError } from '../errors/vizzly-error.js';
+
+/**
+ * Resolve image buffer from file path or return buffer as-is
+ * Handles both Buffer inputs and file path strings, with proper validation and error handling
+ *
+ * @param {Buffer|string} imageBufferOrPath - Image data as Buffer or file path
+ * @param {string} contextName - Context for error messages (e.g., 'screenshot', 'compare')
+ * @returns {Buffer} The image buffer
+ * @throws {VizzlyError} When file not found, unreadable, or invalid input type
+ *
+ * @example
+ * // With Buffer
+ * const buffer = resolveImageBuffer(myBuffer, 'screenshot');
+ *
+ * @example
+ * // With file path
+ * const buffer = resolveImageBuffer('./my-image.png', 'screenshot');
+ */
+export function resolveImageBuffer(imageBufferOrPath, contextName) {
+  // Return Buffer as-is
+  if (Buffer.isBuffer(imageBufferOrPath)) {
+    return imageBufferOrPath;
+  }
+
+  // Validate input type
+  if (typeof imageBufferOrPath !== 'string') {
+    throw new VizzlyError(`Invalid image input: expected Buffer or file path string`, 'INVALID_INPUT', {
+      contextName,
+      type: typeof imageBufferOrPath
+    });
+  }
+
+  // Resolve to absolute path for consistent behavior
+  const filePath = resolve(imageBufferOrPath);
+
+  // Check file exists
+  if (!existsSync(filePath)) {
+    throw new VizzlyError(`Screenshot file not found: ${imageBufferOrPath}`, 'FILE_NOT_FOUND', {
+      contextName,
+      filePath,
+      originalPath: imageBufferOrPath
+    });
+  }
+
+  // Read file with error handling
+  try {
+    return readFileSync(filePath);
+  } catch (error) {
+    throw new VizzlyError(`Failed to read screenshot file: ${imageBufferOrPath} - ${error.message}`, 'FILE_READ_ERROR', {
+      contextName,
+      filePath,
+      originalPath: imageBufferOrPath,
+      originalError: error.message
+    });
+  }
+}

package/dist/utils/global-config.js

@@ -0,0 +1,259 @@
+/**
+ * Global User Configuration Utilities
+ * Manages ~/.vizzly/config.json for storing authentication tokens
+ */
+
+import { homedir } from 'os';
+import { join, dirname, parse } from 'path';
+import { readFile, writeFile, mkdir, chmod } from 'fs/promises';
+import { existsSync } from 'fs';
+
+/**
+ * Get the path to the global Vizzly directory
+ * @returns {string} Path to ~/.vizzly
+ */
+export function getGlobalConfigDir() {
+  return join(homedir(), '.vizzly');
+}
+
+/**
+ * Get the path to the global config file
+ * @returns {string} Path to ~/.vizzly/config.json
+ */
+export function getGlobalConfigPath() {
+  return join(getGlobalConfigDir(), 'config.json');
+}
+
+/**
+ * Ensure the global config directory exists with proper permissions
+ * @returns {Promise<void>}
+ */
+async function ensureGlobalConfigDir() {
+  let dir = getGlobalConfigDir();
+  if (!existsSync(dir)) {
+    await mkdir(dir, {
+      recursive: true,
+      mode: 0o700
+    });
+  }
+}
+
+/**
+ * Load the global configuration
+ * @returns {Promise<Object>} Global config object
+ */
+export async function loadGlobalConfig() {
+  try {
+    let configPath = getGlobalConfigPath();
+    if (!existsSync(configPath)) {
+      return {};
+    }
+    let content = await readFile(configPath, 'utf-8');
+    return JSON.parse(content);
+  } catch (error) {
+    // If file doesn't exist or is corrupted, return empty config
+    if (error.code === 'ENOENT') {
+      return {};
+    }
+
+    // Log warning about corrupted config but don't crash
+    console.warn('Warning: Global config file is corrupted, ignoring');
+    return {};
+  }
+}
+
+/**
+ * Save the global configuration
+ * @param {Object} config - Configuration object to save
+ * @returns {Promise<void>}
+ */
+export async function saveGlobalConfig(config) {
+  await ensureGlobalConfigDir();
+  let configPath = getGlobalConfigPath();
+  let content = JSON.stringify(config, null, 2);
+
+  // Write file with secure permissions (owner read/write only)
+  await writeFile(configPath, content, {
+    mode: 0o600
+  });
+
+  // Ensure permissions are set correctly (in case umask interfered)
+  try {
+    await chmod(configPath, 0o600);
+  } catch (error) {
+    // On Windows, chmod may not work as expected, but that's okay
+    if (process.platform !== 'win32') {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Clear all global configuration
+ * @returns {Promise<void>}
+ */
+export async function clearGlobalConfig() {
+  await saveGlobalConfig({});
+}
+
+/**
+ * Get authentication tokens from global config
+ * @returns {Promise<Object|null>} Token object with accessToken, refreshToken, expiresAt, user, or null if not found
+ */
+export async function getAuthTokens() {
+  let config = await loadGlobalConfig();
+  if (!config.auth || !config.auth.accessToken) {
+    return null;
+  }
+  return config.auth;
+}
+
+/**
+ * Save authentication tokens to global config
+ * @param {Object} auth - Auth object with accessToken, refreshToken, expiresAt, user
+ * @returns {Promise<void>}
+ */
+export async function saveAuthTokens(auth) {
+  let config = await loadGlobalConfig();
+  config.auth = {
+    accessToken: auth.accessToken,
+    refreshToken: auth.refreshToken,
+    expiresAt: auth.expiresAt,
+    user: auth.user
+  };
+  await saveGlobalConfig(config);
+}
+
+/**
+ * Clear authentication tokens from global config
+ * @returns {Promise<void>}
+ */
+export async function clearAuthTokens() {
+  let config = await loadGlobalConfig();
+  delete config.auth;
+  await saveGlobalConfig(config);
+}
+
+/**
+ * Check if authentication tokens exist and are not expired
+ * @returns {Promise<boolean>} True if valid tokens exist
+ */
+export async function hasValidTokens() {
+  let auth = await getAuthTokens();
+  if (!auth || !auth.accessToken) {
+    return false;
+  }
+
+  // Check if token is expired
+  if (auth.expiresAt) {
+    let expiresAt = new Date(auth.expiresAt);
+    let now = new Date();
+
+    // Consider expired if within 5 minutes of expiry
+    let bufferMs = 5 * 60 * 1000;
+    if (now.getTime() >= expiresAt.getTime() - bufferMs) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Get the access token from global config if available
+ * @returns {Promise<string|null>} Access token or null
+ */
+export async function getAccessToken() {
+  let auth = await getAuthTokens();
+  return auth?.accessToken || null;
+}
+
+/**
+ * Get project mapping for a directory
+ * Walks up the directory tree to find the closest mapping
+ * @param {string} directoryPath - Absolute path to project directory
+ * @returns {Promise<Object|null>} Project data or null
+ */
+export async function getProjectMapping(directoryPath) {
+  let config = await loadGlobalConfig();
+  if (!config.projects) {
+    if (process.env.DEBUG_CONFIG) {
+      console.log('[MAPPING] No projects in global config');
+    }
+    return null;
+  }
+
+  // Walk up the directory tree looking for a mapping
+  let currentPath = directoryPath;
+  let {
+    root
+  } = parse(currentPath);
+  if (process.env.DEBUG_CONFIG) {
+    console.log('[MAPPING] Starting lookup from:', currentPath);
+    console.log('[MAPPING] Available mappings:', Object.keys(config.projects));
+  }
+  while (currentPath !== root) {
+    if (process.env.DEBUG_CONFIG) {
+      console.log('[MAPPING] Checking:', currentPath);
+    }
+    if (config.projects[currentPath]) {
+      if (process.env.DEBUG_CONFIG) {
+        console.log('[MAPPING] Found match at:', currentPath);
+      }
+      return config.projects[currentPath];
+    }
+
+    // Move to parent directory
+    let parentPath = dirname(currentPath);
+    if (parentPath === currentPath) {
+      // We've reached the root
+      break;
+    }
+    currentPath = parentPath;
+  }
+  if (process.env.DEBUG_CONFIG) {
+    console.log('[MAPPING] No mapping found');
+  }
+  return null;
+}
+
+/**
+ * Save project mapping for a directory
+ * @param {string} directoryPath - Absolute path to project directory
+ * @param {Object} projectData - Project configuration
+ * @param {string} projectData.token - Project API token (vzt_...)
+ * @param {string} projectData.projectSlug - Project slug
+ * @param {string} projectData.organizationSlug - Organization slug
+ * @param {string} projectData.projectName - Project name
+ */
+export async function saveProjectMapping(directoryPath, projectData) {
+  let config = await loadGlobalConfig();
+  if (!config.projects) {
+    config.projects = {};
+  }
+  config.projects[directoryPath] = {
+    ...projectData,
+    createdAt: new Date().toISOString()
+  };
+  await saveGlobalConfig(config);
+}
+
+/**
+ * Get all project mappings
+ * @returns {Promise<Object>} Map of directory paths to project data
+ */
+export async function getProjectMappings() {
+  let config = await loadGlobalConfig();
+  return config.projects || {};
+}
+
+/**
+ * Delete project mapping for a directory
+ * @param {string} directoryPath - Absolute path to project directory
+ */
+export async function deleteProjectMapping(directoryPath) {
+  let config = await loadGlobalConfig();
+  if (config.projects && config.projects[directoryPath]) {
+    delete config.projects[directoryPath];
+    await saveGlobalConfig(config);
+  }
+}

package/docs/api-reference.md

@@ -12,7 +12,7 @@ Capture a screenshot for visual regression testing.
 
 **Parameters:**
 - `name` (string) - Unique screenshot identifier
-- `imageBuffer` (Buffer) - PNG image data as Buffer
+- `imageBuffer` (Buffer | string) - PNG image data as Buffer, or file path to an image
 - `options` (object, optional) - Configuration and metadata
 
 **Options:**
@@ -20,7 +20,7 @@ Capture a screenshot for visual regression testing.
 {
   // Comparison settings
   threshold: 0.01,           // Pixel difference threshold (0-1)
-  
+
   // Metadata for organization (all optional)
   properties: {
     browser: 'chrome',       // Browser name
@@ -39,7 +39,10 @@ Capture a screenshot for visual regression testing.
 
 **Returns:** `Promise<void>`
 
-**Example:**
+**Examples:**
+
+Using a Buffer:
+
 ```javascript
 import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
 
@@ -54,6 +57,31 @@ await vizzlyScreenshot('homepage', screenshot, {
 });
 ```
 
+Using a file path:
+
+```javascript
+import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+
+// Save screenshot to file
+await page.screenshot({ path: './screenshots/homepage.png' });
+
+// Send to Vizzly using file path
+await vizzlyScreenshot('homepage', './screenshots/homepage.png', {
+  threshold: 0.02,
+  properties: {
+    browser: 'chrome',
+    viewport: '1920x1080',
+    component: 'hero-section'
+  }
+});
+```
+
+**File Path Support:**
+- Accepts both absolute and relative paths
+- Automatically reads the file and converts to Buffer internally
+- Throws error if file doesn't exist or cannot be read
+- Works with any PNG image file
+
 ### `vizzlyFlush()`
 
 Wait for all queued screenshots to be processed.
@@ -201,10 +229,24 @@ Stop the Vizzly server and cleanup resources.
 **Returns:** `Promise<void>`
 
 ##### `screenshot(name, imageBuffer, options)`
-Capture a screenshot (same as client API).
+Capture a screenshot.
+
+**Parameters:**
+- `name` (string) - Unique screenshot identifier
+- `imageBuffer` (Buffer | string) - PNG image data as Buffer, or file path to an image
+- `options` (object, optional) - Configuration and metadata
 
 **Returns:** `Promise<void>`
 
+**Example:**
+```javascript
+// Using a Buffer
+await vizzly.screenshot('homepage', buffer);
+
+// Using a file path
+await vizzly.screenshot('homepage', './screenshots/homepage.png');
+```
+
 ##### `upload(options)`
 Upload screenshots to Vizzly.
 
@@ -224,8 +266,21 @@ Upload screenshots to Vizzly.
 ##### `compare(name, imageBuffer)`
 Run local comparison (TDD mode).
 
+**Parameters:**
+- `name` (string) - Screenshot name
+- `imageBuffer` (Buffer | string) - PNG image data as Buffer, or file path to an image
+
 **Returns:** `Promise<ComparisonResult>`
 
+**Example:**
+```javascript
+// Using a Buffer
+const result = await vizzly.compare('homepage', buffer);
+
+// Using a file path
+const result = await vizzly.compare('homepage', './screenshots/homepage.png');
+```
+
 ##### `getConfig()`
 Get current SDK configuration.
 
@@ -271,6 +326,117 @@ vizzly.on('comparison:failed', (error) => {
 
 ## CLI Commands
 
+### Authentication Commands
+
+#### `vizzly login`
+
+Authenticate using OAuth 2.0 device flow.
+
+**Options:**
+- `--json` - Machine-readable JSON output
+- `--verbose` - Verbose output
+
+**Exit Codes:**
+- `0` - Login successful
+- `1` - Login failed
+
+**Example:**
+```bash
+vizzly login
+```
+
+#### `vizzly logout`
+
+Clear stored authentication tokens.
+
+**Options:**
+- `--json` - Machine-readable JSON output
+- `--verbose` - Verbose output
+
+**Exit Codes:**
+- `0` - Logout successful
+- `1` - Logout failed
+
+**Example:**
+```bash
+vizzly logout
+```
+
+#### `vizzly whoami`
+
+Display current user and authentication status.
+
+**Options:**
+- `--json` - Machine-readable JSON output
+
+**Exit Codes:**
+- `0` - Success
+- `1` - Not authenticated or error
+
+**Example:**
+```bash
+vizzly whoami
+```
+
+#### `vizzly project:select`
+
+Configure project-specific token for current directory.
+
+**Options:**
+- `--json` - Machine-readable JSON output
+
+**Exit Codes:**
+- `0` - Project configured successfully
+- `1` - Configuration failed
+
+**Example:**
+```bash
+cd /path/to/project
+vizzly project:select
+```
+
+#### `vizzly project:list`
+
+Show all configured projects.
+
+**Exit Codes:**
+- `0` - Success
+- `1` - Error
+
+**Example:**
+```bash
+vizzly project:list
+```
+
+#### `vizzly project:token`
+
+Display project token for current directory.
+
+**Options:**
+- `--json` - Machine-readable JSON output
+
+**Exit Codes:**
+- `0` - Success
+- `1` - No project configured or error
+
+**Example:**
+```bash
+vizzly project:token
+```
+
+#### `vizzly project:remove`
+
+Remove project configuration for current directory.
+
+**Exit Codes:**
+- `0` - Success
+- `1` - No project configured or error
+
+**Example:**
+```bash
+vizzly project:remove
+```
+
 ### `vizzly upload <path>`
 
 Upload screenshots from a directory.
@@ -502,9 +668,14 @@ Configuration loaded via cosmiconfig in this order:
 
 ### Environment Variables
 
+**Authentication:**
+- `VIZZLY_TOKEN` - API authentication token (project token or access token)
+  - For local development: Use `vizzly login` instead of manually managing tokens
+  - For CI/CD: Use project tokens from environment variables
+  - Token priority: CLI flag → env var → project mapping → user access token
+
 **Core Configuration:**
-- `VIZZLY_TOKEN` - API authentication token
-- `VIZZLY_API_URL` - API base URL override
+- `VIZZLY_API_URL` - API base URL override (default: `https://app.vizzly.dev`)
 - `VIZZLY_LOG_LEVEL` - Logger level (`debug`, `info`, `warn`, `error`)
 
 **Parallel Builds:**