@vizzly-testing/cli 0.1.0

package/dist/utils/environment.js

@@ -0,0 +1,109 @@
+/**
+ * Environment detection utilities for handling CI/interactive environments
+ */
+
+/**
+ * Check if running in a CI environment
+ * Based on common CI environment variables
+ * @returns {boolean} True if running in CI
+ */
+export function isCI() {
+  return Boolean(process.env.CI ||
+  // Generic CI flag
+  process.env.CONTINUOUS_INTEGRATION ||
+  // TravisCI, CircleCI
+  process.env.BUILD_NUMBER ||
+  // Jenkins
+  process.env.GITHUB_ACTIONS ||
+  // GitHub Actions
+  process.env.GITLAB_CI ||
+  // GitLab CI
+  process.env.CIRCLECI ||
+  // CircleCI
+  process.env.TRAVIS ||
+  // TravisCI
+  process.env.APPVEYOR ||
+  // AppVeyor
+  process.env.CODEBUILD_BUILD_ID ||
+  // AWS CodeBuild
+  process.env.TEAMCITY_VERSION ||
+  // TeamCity
+  process.env.TF_BUILD ||
+  // Azure DevOps
+  process.env.DRONE ||
+  // Drone CI
+  process.env.BITBUCKET_BUILD_NUMBER // Bitbucket Pipelines
+  );
+}
+
+/**
+ * Check if stdout supports interactive features
+ * @returns {boolean} True if interactive features are supported
+ */
+export function isInteractiveTerminal() {
+  return Boolean(process.stdout.isTTY && process.stdin.isTTY && (!process.env.TERM || process.env.TERM !== 'dumb'));
+}
+
+/**
+ * Determine if interactive mode should be enabled
+ * Takes into account CI detection, TTY support, and explicit flags
+ * @param {Object} options
+ * @param {boolean} [options.noInteractive] - Explicit flag to disable interactive mode
+ * @param {boolean} [options.interactive] - Explicit flag to force interactive mode
+ * @returns {boolean} True if interactive mode should be enabled
+ */
+export function shouldUseInteractiveMode(options = {}) {
+  // Explicit flags take priority
+  // Commander.js sets interactive=false when --no-interactive is used
+  if (options.interactive === false) {
+    return false;
+  }
+  if (options.interactive === true) {
+    return true;
+  }
+
+  // Legacy support for explicit noInteractive flag
+  if (options.noInteractive === true) {
+    return false;
+  }
+
+  // Auto-detect based on environment
+  return !isCI() && isInteractiveTerminal();
+}
+
+/**
+ * Get environment type for logging/debugging
+ * @returns {string} Environment type description
+ */
+export function getEnvironmentType() {
+  if (isCI()) {
+    return 'CI';
+  }
+  if (!isInteractiveTerminal()) {
+    return 'non-interactive';
+  }
+  return 'interactive';
+}
+
+/**
+ * Get detailed environment info for debugging
+ * @returns {Object} Environment details
+ */
+export function getEnvironmentDetails() {
+  return {
+    isCI: isCI(),
+    isInteractiveTerminal: isInteractiveTerminal(),
+    environmentType: getEnvironmentType(),
+    stdoutIsTTY: Boolean(process.stdout.isTTY),
+    stdinIsTTY: Boolean(process.stdin.isTTY),
+    ciVars: {
+      CI: process.env.CI,
+      CONTINUOUS_INTEGRATION: process.env.CONTINUOUS_INTEGRATION,
+      GITHUB_ACTIONS: process.env.GITHUB_ACTIONS,
+      GITLAB_CI: process.env.GITLAB_CI,
+      CIRCLECI: process.env.CIRCLECI,
+      TRAVIS: process.env.TRAVIS
+    },
+    termType: process.env.TERM
+  };
+}

package/dist/utils/error-messages.js

@@ -0,0 +1,34 @@
+export const ERROR_MESSAGES = {
+  NO_API_TOKEN: {
+    message: 'No API token provided',
+    hint: 'Set the VIZZLY_TOKEN environment variable or pass --token flag',
+    docs: 'https://github.com/vizzly-testing/cli#set-up-your-api-token'
+  },
+  BUILD_CREATION_FAILED: {
+    message: 'Failed to create build',
+    hint: 'Check your API token permissions and network connection',
+    docs: 'https://github.com/vizzly-testing/cli/blob/main/docs/upload-command.md#troubleshooting'
+  },
+  NO_SCREENSHOTS_FOUND: {
+    message: 'No screenshots found',
+    hint: 'Make sure your test code calls vizzlyScreenshot() or check the screenshots directory',
+    docs: 'https://github.com/vizzly-testing/cli/blob/main/docs/getting-started.md'
+  },
+  PORT_IN_USE: {
+    message: 'Port is already in use',
+    hint: 'Try a different port with --port flag or stop the process using this port',
+    docs: 'https://github.com/vizzly-testing/cli/blob/main/docs/test-integration.md#troubleshooting'
+  }
+};
+export function formatError(errorCode, context = {}) {
+  const errorInfo = ERROR_MESSAGES[errorCode];
+  if (!errorInfo) return {
+    message: errorCode
+  };
+  return {
+    message: errorInfo.message,
+    hint: errorInfo.hint,
+    docs: errorInfo.docs,
+    context
+  };
+}

package/dist/utils/fetch-utils.js

@@ -0,0 +1,9 @@
+function fetchWithTimeout(url, opts = {}, ms = 300000) {
+  let ctrl = new AbortController();
+  let id = setTimeout(() => ctrl.abort(), ms);
+  return fetch(url, {
+    ...opts,
+    signal: ctrl.signal
+  }).finally(() => clearTimeout(id));
+}
+export { fetchWithTimeout };

package/dist/utils/framework-detector.js

@@ -0,0 +1,40 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Detect testing framework from project dependencies
+ * @returns {Promise<string|null>} Detected framework or null
+ */
+export async function detectFramework() {
+  try {
+    const packageJsonPath = path.join(process.cwd(), 'package.json');
+    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+    const dependencies = {
+      ...(packageJson.dependencies || {}),
+      ...(packageJson.devDependencies || {})
+    };
+
+    // Check for common testing frameworks
+    if (dependencies['@playwright/test'] || dependencies.playwright) {
+      return 'playwright';
+    }
+    if (dependencies.cypress) {
+      return 'cypress';
+    }
+    if (dependencies.puppeteer) {
+      return 'puppeteer';
+    }
+
+    // Check for config files
+    const files = await fs.readdir(process.cwd());
+    if (files.some(f => f.includes('playwright.config'))) {
+      return 'playwright';
+    }
+    if (files.some(f => f.includes('cypress.config'))) {
+      return 'cypress';
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/dist/utils/git.js

@@ -0,0 +1,226 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+export async function getCommonAncestor(commit1, commit2, cwd = process.cwd()) {
+  try {
+    const {
+      stdout
+    } = await execAsync(`git merge-base ${commit1} ${commit2}`, {
+      cwd
+    });
+    return stdout.trim();
+  } catch {
+    // If merge-base fails (e.g., no common ancestor), return null
+    return null;
+  }
+}
+export async function getCurrentCommitSha(cwd = process.cwd()) {
+  try {
+    const {
+      stdout
+    } = await execAsync('git rev-parse HEAD', {
+      cwd
+    });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+export async function getCurrentBranch(cwd = process.cwd()) {
+  try {
+    const {
+      stdout
+    } = await execAsync('git rev-parse --abbrev-ref HEAD', {
+      cwd
+    });
+    return stdout.trim();
+  } catch {
+    // Fallback strategy: use a simple, non-recursive approach
+    // to avoid circular dependency with getDefaultBranch()
+    return getCurrentBranchFallback(cwd);
+  }
+}
+
+/**
+ * Fallback strategy for getCurrentBranch that doesn't depend on getDefaultBranch()
+ * to avoid circular dependencies. Uses a simple heuristic approach.
+ */
+async function getCurrentBranchFallback(cwd = process.cwd()) {
+  // Try common default branches in order of likelihood
+  const commonBranches = ['main', 'master', 'develop', 'dev'];
+  for (const branch of commonBranches) {
+    try {
+      await execAsync(`git show-ref --verify --quiet refs/heads/${branch}`, {
+        cwd
+      });
+      return branch;
+    } catch {
+      // Branch doesn't exist, try next one
+      continue;
+    }
+  }
+
+  // If none of the common branches exist, try to get any local branch
+  try {
+    const {
+      stdout
+    } = await execAsync('git branch --format="%(refname:short)"', {
+      cwd
+    });
+    const branches = stdout.trim().split('\n').filter(b => b.trim());
+    if (branches.length > 0) {
+      return branches[0]; // Return the first available branch
+    }
+  } catch {
+    // Git branch command failed
+  }
+
+  // Last resort: return null to indicate we couldn't determine the branch
+  // This allows calling code to handle the situation (e.g., prompt user or use 'main')
+  return null;
+}
+export async function getDefaultBranch(cwd = process.cwd()) {
+  try {
+    // Try to get the default branch from remote origin
+    const {
+      stdout
+    } = await execAsync('git symbolic-ref refs/remotes/origin/HEAD', {
+      cwd
+    });
+    const defaultBranch = stdout.trim().replace('refs/remotes/origin/', '');
+    return defaultBranch;
+  } catch {
+    try {
+      // Fallback: try to get default branch from git config
+      const {
+        stdout
+      } = await execAsync('git config --get init.defaultBranch', {
+        cwd
+      });
+      return stdout.trim();
+    } catch {
+      try {
+        // Fallback: check if main exists
+        await execAsync('git show-ref --verify --quiet refs/heads/main', {
+          cwd
+        });
+        return 'main';
+      } catch {
+        try {
+          // Fallback: check if master exists
+          await execAsync('git show-ref --verify --quiet refs/heads/master', {
+            cwd
+          });
+          return 'master';
+        } catch {
+          // If we're not in a git repo or no branches exist, return null
+          // This allows the calling code to handle the situation appropriately
+          return null;
+        }
+      }
+    }
+  }
+}
+export function generateBuildName() {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return `Build ${timestamp}`;
+}
+
+/**
+ * Get the current commit message
+ * @param {string} cwd - Working directory
+ * @returns {Promise<string|null>} Commit message or null if not available
+ */
+export async function getCommitMessage(cwd = process.cwd()) {
+  try {
+    const {
+      stdout
+    } = await execAsync('git log -1 --pretty=%B', {
+      cwd
+    });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the working directory is a git repository
+ * @param {string} cwd - Working directory
+ * @returns {Promise<boolean>}
+ */
+export async function isGitRepository(cwd = process.cwd()) {
+  try {
+    await execAsync('git rev-parse --git-dir', {
+      cwd
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get git status information
+ * @param {string} cwd - Working directory
+ * @returns {Promise<Object|null>} Git status info or null
+ */
+export async function getGitStatus(cwd = process.cwd()) {
+  try {
+    const {
+      stdout
+    } = await execAsync('git status --porcelain', {
+      cwd
+    });
+    const changes = stdout.trim().split('\n').filter(line => line);
+    return {
+      hasChanges: changes.length > 0,
+      changes: changes.map(line => ({
+        status: line.substring(0, 2),
+        file: line.substring(3)
+      }))
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Detect branch with override support
+ * @param {string} override - Branch override from CLI
+ * @param {string} cwd - Working directory
+ * @returns {Promise<string>}
+ */
+export async function detectBranch(override = null, cwd = process.cwd()) {
+  if (override) return override;
+  const currentBranch = await getCurrentBranch(cwd);
+  return currentBranch || 'unknown';
+}
+
+/**
+ * Detect commit SHA with override support
+ * @param {string} override - Commit override from CLI
+ * @param {string} cwd - Working directory
+ * @returns {Promise<string|null>}
+ */
+export async function detectCommit(override = null, cwd = process.cwd()) {
+  if (override) return override;
+  return await getCurrentCommitSha(cwd);
+}
+
+/**
+ * Generate build name with git information
+ * @param {string} override - Build name override from CLI
+ * @param {string} cwd - Working directory
+ * @returns {Promise<string>}
+ */
+export async function generateBuildNameWithGit(override = null, cwd = process.cwd()) {
+  if (override) return override;
+  const branch = await getCurrentBranch(cwd);
+  const shortSha = await getCurrentCommitSha(cwd);
+  if (branch && shortSha) {
+    const shortCommit = shortSha.substring(0, 7);
+    return `${branch}-${shortCommit}`;
+  }
+  return generateBuildName();
+}

package/dist/utils/help.js

@@ -0,0 +1,66 @@
+import { createColors } from './colors.js';
+
+/**
+ * Display help information for the CLI
+ * @param {Object} globalOptions - Global CLI options
+ */
+export function showHelp(globalOptions = {}) {
+  const colors = createColors({
+    useColor: !globalOptions.noColor
+  });
+  if (globalOptions.json) {
+    console.log(JSON.stringify({
+      status: 'info',
+      message: 'Vizzly CLI Help',
+      commands: [{
+        name: 'run',
+        description: 'Run tests with Vizzly visual testing'
+      }, {
+        name: 'upload',
+        description: 'Upload screenshots to Vizzly'
+      }, {
+        name: 'init',
+        description: 'Initialize Vizzly configuration'
+      }],
+      timestamp: new Date().toISOString()
+    }));
+    return;
+  }
+  console.log('');
+  console.log(colors.cyan(colors.bold('🔍 Vizzly CLI')));
+  console.log(colors.dim('Visual testing tool for UI developers'));
+  console.log('');
+  console.log(colors.yellow(colors.bold('Available Commands:')));
+  console.log('');
+  console.log(`  ${colors.green(colors.bold('run'))}     Run tests with Vizzly visual testing`);
+  console.log(`  ${colors.green(colors.bold('upload'))}  Upload screenshots to Vizzly`);
+  console.log(`  ${colors.green(colors.bold('init'))}    Initialize Vizzly configuration`);
+  console.log('');
+  console.log(colors.dim('Use ') + colors.cyan('vizzly <command> --help') + colors.dim(' for command-specific options'));
+  console.log('');
+}
+
+/**
+ * Show error for unknown command
+ * @param {string} command - Unknown command name
+ * @param {Object} globalOptions - Global CLI options
+ */
+export function showUnknownCommand(command, globalOptions = {}) {
+  const colors = createColors({
+    useColor: !globalOptions.noColor
+  });
+  if (globalOptions.json) {
+    console.error(JSON.stringify({
+      status: 'error',
+      message: `Unknown command: ${command}`,
+      availableCommands: ['run', 'upload', 'init'],
+      timestamp: new Date().toISOString()
+    }));
+    process.exit(1);
+  }
+  console.error(colors.red(`✖ Unknown command: ${command}`));
+  console.error('');
+  console.error(colors.dim('Available commands: run, upload, init'));
+  console.error('');
+  process.exit(1);
+}

package/dist/utils/image-comparison.js

@@ -0,0 +1,172 @@
+import { compare } from 'odiff-bin';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import { VizzlyError } from '../errors/vizzly-error.js';
+
+/**
+ * Compare two images and return the difference
+ * @param {Buffer} imageBuffer1 - First image buffer
+ * @param {Buffer} imageBuffer2 - Second image buffer
+ * @param {Object} options - Comparison options
+ * @param {number} options.threshold - Matching threshold (0-1)
+ * @param {boolean} options.ignoreAntialiasing - Ignore antialiasing
+ * @param {boolean} options.ignoreColors - Ignore colors (not supported by odiff)
+ * @param {Array} options.ignoreRegions - Regions to ignore in comparison
+ * @returns {Promise<Object>} Comparison result
+ */
+export async function compareImages(imageBuffer1, imageBuffer2, options = {}) {
+  // Create temporary files for odiff
+  const tempDir = os.tmpdir();
+  const tempId = crypto.randomBytes(8).toString('hex');
+  const basePath = path.join(tempDir, `vizzly-base-${tempId}.png`);
+  const comparePath = path.join(tempDir, `vizzly-compare-${tempId}.png`);
+  const diffPath = path.join(tempDir, `vizzly-diff-${tempId}.png`);
+  try {
+    // Write buffers to temporary files
+    await fs.writeFile(basePath, imageBuffer1);
+    await fs.writeFile(comparePath, imageBuffer2);
+
+    // Configure odiff options
+    const odiffOptions = {
+      threshold: options.threshold || 0.1,
+      antialiasing: options.ignoreAntialiasing !== false,
+      outputDiffMask: true,
+      failOnLayoutDiff: false,
+      noFailOnFsErrors: false,
+      diffColor: '#ff0000',
+      // Red for differences
+      captureDiffLines: true,
+      reduceRamUsage: false,
+      ignoreRegions: options.ignoreRegions || []
+    };
+
+    // Run odiff comparison
+    const result = await compare(basePath, comparePath, diffPath, odiffOptions);
+
+    // Process results
+    if (result.match) {
+      return {
+        misMatchPercentage: 0,
+        diffPixels: 0,
+        totalPixels: 0,
+        dimensionDifference: {
+          width: 0,
+          height: 0
+        },
+        diffBuffer: null
+      };
+    }
+
+    // Handle different failure reasons
+    switch (result.reason) {
+      case 'layout-diff':
+        {
+          return {
+            misMatchPercentage: 100,
+            dimensionDifference: {
+              width: 'unknown',
+              height: 'unknown'
+            },
+            error: 'Image dimensions do not match',
+            diffBuffer: null
+          };
+        }
+      case 'pixel-diff':
+        {
+          // Read the diff image
+          const diffBuffer = await fs.readFile(diffPath);
+          return {
+            misMatchPercentage: result.diffPercentage,
+            diffPixels: result.diffCount,
+            totalPixels: Math.round(result.diffCount / (result.diffPercentage / 100)),
+            dimensionDifference: {
+              width: 0,
+              height: 0
+            },
+            diffBuffer,
+            diffLines: result.diffLines
+          };
+        }
+      case 'file-not-exists':
+        throw new VizzlyError(`Image file not found: ${result.file}`, 'IMAGE_NOT_FOUND', {
+          file: result.file
+        });
+      default:
+        throw new VizzlyError('Unknown comparison result', 'COMPARISON_UNKNOWN', {
+          result
+        });
+    }
+  } catch (error) {
+    // Re-throw VizzlyErrors
+    if (error instanceof VizzlyError) {
+      throw error;
+    }
+    throw new VizzlyError('Failed to compare images', 'IMAGE_COMPARISON_FAILED', {
+      error: error.message
+    });
+  } finally {
+    // Clean up temporary files
+    await Promise.all([fs.unlink(basePath).catch(() => {}), fs.unlink(comparePath).catch(() => {}), fs.unlink(diffPath).catch(() => {})]);
+  }
+}
+
+/**
+ * Check if buffer is a valid PNG image
+ * @param {Buffer} buffer - Image buffer
+ * @returns {boolean} True if valid PNG
+ */
+export function isValidPNG(buffer) {
+  // Check PNG signature
+  if (!buffer || buffer.length < 8) {
+    return false;
+  }
+
+  // PNG signature: 137 80 78 71 13 10 26 10
+  const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+  return buffer.subarray(0, 8).equals(pngSignature);
+}
+
+/**
+ * Get image dimensions from PNG buffer
+ * @param {Buffer} buffer - Image buffer
+ * @returns {Object|null} Dimensions or null if invalid
+ */
+export function getImageDimensions(buffer) {
+  if (!isValidPNG(buffer)) {
+    return null;
+  }
+  try {
+    // PNG dimensions are stored in the IHDR chunk
+    // Skip PNG signature (8 bytes) + chunk length (4 bytes) + chunk type (4 bytes)
+    const width = buffer.readUInt32BE(16);
+    const height = buffer.readUInt32BE(20);
+    return {
+      width,
+      height
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compare images with ignore regions
+ * @param {Buffer} imageBuffer1 - First image buffer
+ * @param {Buffer} imageBuffer2 - Second image buffer
+ * @param {Array<{x: number, y: number, width: number, height: number}>} ignoreRegions - Regions to ignore
+ * @returns {Promise<Object>} Comparison result
+ */
+export async function compareImagesWithIgnoreRegions(imageBuffer1, imageBuffer2, ignoreRegions = []) {
+  // Convert ignore regions to odiff format
+  const odiffIgnoreRegions = ignoreRegions.map(region => ({
+    x1: region.x,
+    y1: region.y,
+    x2: region.x + region.width,
+    y2: region.y + region.height
+  }));
+  return compareImages(imageBuffer1, imageBuffer2, {
+    ignoreRegions: odiffIgnoreRegions
+  });
+}