@vizzly-testing/cli 0.10.3 → 0.11.1

package/claude-plugin/mcp/vizzly-server/local-tdd-provider.js

@@ -0,0 +1,422 @@
+import { readFile, readdir, stat, access, copyFile, mkdir, writeFile } from 'fs/promises';
+import { join, resolve } from 'path';
+import { constants } from 'fs';
+
+/**
+ * Provider for reading local TDD state from .vizzly directory
+ */
+export class LocalTDDProvider {
+  /**
+   * Find .vizzly directory by searching up from current directory
+   */
+  async findVizzlyDir(workingDirectory = process.cwd()) {
+    let currentDir = resolve(workingDirectory);
+    let maxDepth = 10;
+    let depth = 0;
+
+    while (depth < maxDepth) {
+      let vizzlyDir = join(currentDir, '.vizzly');
+      try {
+        await access(vizzlyDir, constants.R_OK);
+        return vizzlyDir;
+      } catch {
+        // Directory doesn't exist or isn't readable, go up one level
+        let parentDir = join(currentDir, '..');
+        if (parentDir === currentDir) {
+          // Reached root
+          break;
+        }
+        currentDir = parentDir;
+        depth++;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Get baseline metadata if available
+   * Returns metadata about cloud build that baselines were downloaded from
+   */
+  async getBaselineMetadata(workingDirectory) {
+    let vizzlyDir = await this.findVizzlyDir(workingDirectory);
+    if (!vizzlyDir) {
+      return null;
+    }
+
+    let metadataPath = join(vizzlyDir, 'baseline-metadata.json');
+    try {
+      let content = await readFile(metadataPath, 'utf-8');
+      return JSON.parse(content);
+    } catch {
+      // No metadata file exists (expected for local-only baselines)
+      return null;
+    }
+  }
+
+  /**
+   * Get TDD server information from server.json
+   */
+  async getServerInfo(workingDirectory) {
+    let vizzlyDir = await this.findVizzlyDir(workingDirectory);
+    if (!vizzlyDir) {
+      return {
+        running: false,
+        message: 'No .vizzly directory found. TDD server not running.'
+      };
+    }
+
+    let serverJsonPath = join(vizzlyDir, 'server.json');
+    try {
+      let content = await readFile(serverJsonPath, 'utf-8');
+      let serverInfo = JSON.parse(content);
+      return {
+        running: true,
+        ...serverInfo,
+        dashboardUrl: `http://localhost:${serverInfo.port}/dashboard`
+      };
+    } catch {
+      return {
+        running: false,
+        message: 'TDD server not running or server.json not found',
+        vizzlyDir
+      };
+    }
+  }
+
+  /**
+   * Get current TDD status with comparison results
+   */
+  async getTDDStatus(workingDirectory) {
+    let vizzlyDir = await this.findVizzlyDir(workingDirectory);
+    if (!vizzlyDir) {
+      return {
+        error: 'No .vizzly directory found',
+        message: 'Run `vizzly tdd start` or `vizzly tdd run "npm test"` to initialize TDD mode'
+      };
+    }
+
+    let serverInfo = await this.getServerInfo(workingDirectory);
+
+    // Read comparison results from report data
+    let reportDataPath = join(vizzlyDir, 'report-data.json');
+    let comparisons = [];
+    let summary = {
+      total: 0,
+      passed: 0,
+      failed: 0,
+      new: 0
+    };
+
+    try {
+      let reportData = await readFile(reportDataPath, 'utf-8');
+      let data = JSON.parse(reportData);
+      comparisons = data.comparisons || [];
+
+      // Calculate summary
+      summary.total = comparisons.length;
+      summary.passed = comparisons.filter((c) => c.status === 'passed').length;
+      summary.failed = comparisons.filter((c) => c.status === 'failed').length;
+      summary.new = comparisons.filter((c) => c.status === 'new').length;
+    } catch {
+      // No comparisons yet
+    }
+
+    // List available diff images
+    let diffsDir = join(vizzlyDir, 'diffs');
+    let diffImages = [];
+    try {
+      let files = await readdir(diffsDir);
+      diffImages = files
+        .filter((f) => f.endsWith('.png'))
+        .map((f) => ({
+          name: f.replace('.png', ''),
+          path: join(diffsDir, f)
+        }));
+    } catch {
+      // No diffs directory
+    }
+
+    // Get baseline metadata if available
+    let baselineMetadata = await this.getBaselineMetadata(workingDirectory);
+
+    return {
+      vizzlyDir,
+      serverInfo,
+      summary,
+      comparisons: comparisons.map((c) => {
+        // Convert paths from report-data.json to filesystem paths
+        // Report paths like "/images/baselines/foo.png" -> ".vizzly/baselines/foo.png"
+        let makeFilesystemPath = (path) => {
+          if (!path) return null;
+          // Strip /images/ prefix and join with vizzlyDir
+          let cleanPath = path.replace(/^\/images\//, '');
+          return join(vizzlyDir, cleanPath);
+        };
+
+        return {
+          name: c.name,
+          status: c.status,
+          diffPercentage: c.diffPercentage,
+          threshold: c.threshold,
+          hasDiff: c.diffPercentage > c.threshold,
+          currentPath: makeFilesystemPath(c.current),
+          baselinePath: makeFilesystemPath(c.baseline),
+          diffPath: makeFilesystemPath(c.diff)
+        };
+      }),
+      diffImages,
+      failedComparisons: comparisons.filter((c) => c.status === 'failed').map((c) => c.name),
+      newScreenshots: comparisons.filter((c) => c.status === 'new').map((c) => c.name),
+      baselineMetadata
+    };
+  }
+
+  /**
+   * Get detailed information about a specific comparison
+   */
+  async getComparisonDetails(screenshotName, workingDirectory) {
+    let status = await this.getTDDStatus(workingDirectory);
+    if (status.error) {
+      return status;
+    }
+
+    let comparison = status.comparisons.find((c) => c.name === screenshotName);
+    if (!comparison) {
+      return {
+        error: `Screenshot "${screenshotName}" not found`,
+        availableScreenshots: status.comparisons.map((c) => c.name)
+      };
+    }
+
+    return {
+      ...comparison,
+      mode: 'local',
+      vizzlyDir: status.vizzlyDir,
+      baselineMetadata: status.baselineMetadata,
+      analysis: this.analyzeComparison(comparison)
+    };
+  }
+
+  /**
+   * Analyze comparison to provide helpful insights
+   */
+  analyzeComparison(comparison) {
+    let insights = [];
+
+    if (comparison.status === 'new') {
+      insights.push('This is a new screenshot with no baseline for comparison.');
+      insights.push('Accept this screenshot as the baseline if it looks correct.');
+    } else if (comparison.status === 'failed') {
+      let diffPct = comparison.diffPercentage;
+      if (diffPct < 1) {
+        insights.push(
+          `Small difference detected (${diffPct.toFixed(2)}%). This might be minor anti-aliasing or subpixel rendering.`
+        );
+      } else if (diffPct < 5) {
+        insights.push(
+          `Moderate difference (${diffPct.toFixed(2)}%). Likely a layout shift or color change.`
+        );
+      } else {
+        insights.push(
+          `Large difference (${diffPct.toFixed(2)}%). Significant visual change detected.`
+        );
+      }
+
+      insights.push(
+        'Use the Read tool to view the baseline and current image paths to identify the differences.'
+      );
+      insights.push('Do NOT attempt to read the diff image path as it may cause API errors.');
+      insights.push('If this change is intentional, accept it as the new baseline.');
+      insights.push('If unintentional, investigate and fix the visual issue.');
+    } else if (comparison.status === 'passed') {
+      insights.push('Screenshot matches the baseline within threshold.');
+    }
+
+    return insights;
+  }
+
+  /**
+   * List all diff images
+   */
+  async listDiffImages(workingDirectory) {
+    let vizzlyDir = await this.findVizzlyDir(workingDirectory);
+    if (!vizzlyDir) {
+      return {
+        error: 'No .vizzly directory found'
+      };
+    }
+
+    let diffsDir = join(vizzlyDir, 'diffs');
+    try {
+      let files = await readdir(diffsDir);
+      let diffImages = [];
+
+      for (let file of files) {
+        if (!file.endsWith('.png')) continue;
+
+        let filePath = join(diffsDir, file);
+        let stats = await stat(filePath);
+
+        diffImages.push({
+          name: file.replace('.png', ''),
+          path: filePath,
+          size: stats.size,
+          modified: stats.mtime
+        });
+      }
+
+      return {
+        count: diffImages.length,
+        diffImages: diffImages.sort((a, b) => b.modified.getTime() - a.modified.getTime())
+      };
+    } catch {
+      return {
+        count: 0,
+        diffImages: [],
+        message: 'No diff images found'
+      };
+    }
+  }
+
+  /**
+   * Accept a screenshot as new baseline
+   * Copies current screenshot to baselines directory
+   */
+  async acceptBaseline(screenshotName, workingDirectory) {
+    let vizzlyDir = await this.findVizzlyDir(workingDirectory);
+    if (!vizzlyDir) {
+      throw new Error('No .vizzly directory found. TDD server not running.');
+    }
+
+    let currentPath = join(vizzlyDir, 'screenshots', `${screenshotName}.png`);
+    let baselinePath = join(vizzlyDir, 'baselines', `${screenshotName}.png`);
+
+    try {
+      // Check current screenshot exists
+      await access(currentPath, constants.R_OK);
+
+      // Ensure baselines directory exists
+      await mkdir(join(vizzlyDir, 'baselines'), { recursive: true });
+
+      // Copy current to baseline
+      await copyFile(currentPath, baselinePath);
+
+      return {
+        success: true,
+        message: `Accepted ${screenshotName} as new baseline`,
+        screenshotName,
+        baselinePath
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to accept baseline: ${error.message}. Make sure the screenshot exists at ${currentPath}`
+      );
+    }
+  }
+
+  /**
+   * Reject a screenshot (marks it for investigation)
+   * Creates a rejection marker file
+   */
+  async rejectBaseline(screenshotName, reason, workingDirectory) {
+    let vizzlyDir = await this.findVizzlyDir(workingDirectory);
+    if (!vizzlyDir) {
+      throw new Error('No .vizzly directory found. TDD server not running.');
+    }
+
+    let rejectionsDir = join(vizzlyDir, 'rejections');
+    await mkdir(rejectionsDir, { recursive: true });
+
+    let rejectionFile = join(rejectionsDir, `${screenshotName}.json`);
+    let rejectionData = {
+      screenshotName,
+      reason,
+      rejectedAt: new Date().toISOString()
+    };
+
+    try {
+      await writeFile(rejectionFile, JSON.stringify(rejectionData, null, 2));
+
+      return {
+        success: true,
+        message: `Rejected ${screenshotName}: ${reason}`,
+        screenshotName,
+        reason
+      };
+    } catch (error) {
+      throw new Error(`Failed to reject baseline: ${error.message}`);
+    }
+  }
+
+  /**
+   * Download and save baselines from cloud build
+   */
+  async downloadBaselinesFromCloud(screenshots, workingDirectory, buildMetadata = null) {
+    let vizzlyDir = await this.findVizzlyDir(workingDirectory);
+    if (!vizzlyDir) {
+      throw new Error('No .vizzly directory found. TDD server not running.');
+    }
+
+    let baselinesDir = join(vizzlyDir, 'baselines');
+    await mkdir(baselinesDir, { recursive: true });
+
+    let results = [];
+
+    for (let screenshot of screenshots) {
+      try {
+        // Download image from URL
+        let response = await fetch(screenshot.url);
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`);
+        }
+
+        // eslint-disable-next-line no-undef
+        let buffer = Buffer.from(await response.arrayBuffer());
+        let baselinePath = join(baselinesDir, `${screenshot.name}.png`);
+
+        await writeFile(baselinePath, buffer);
+
+        results.push({
+          name: screenshot.name,
+          success: true,
+          path: baselinePath
+        });
+      } catch (error) {
+        results.push({
+          name: screenshot.name,
+          success: false,
+          error: error.message
+        });
+      }
+    }
+
+    let successCount = results.filter((r) => r.success).length;
+
+    // Save baseline metadata if build metadata provided
+    if (buildMetadata && successCount > 0) {
+      let metadata = {
+        sourceType: 'cloud-build',
+        buildId: buildMetadata.id,
+        buildName: buildMetadata.name,
+        branch: buildMetadata.branch,
+        commitSha: buildMetadata.commitSha,
+        commitMessage: buildMetadata.commitMessage,
+        commonAncestorSha: buildMetadata.commonAncestorSha,
+        buildUrl: buildMetadata.url,
+        downloadedAt: new Date().toISOString(),
+        screenshots: results.filter((r) => r.success).map((r) => r.name)
+      };
+
+      let metadataPath = join(vizzlyDir, 'baseline-metadata.json');
+      await writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+    }
+
+    return {
+      success: successCount > 0,
+      message: `Downloaded ${successCount}/${screenshots.length} baselines`,
+      results,
+      metadataSaved: buildMetadata && successCount > 0
+    };
+  }
+}

package/claude-plugin/mcp/vizzly-server/token-resolver.js

@@ -0,0 +1,185 @@
+/**
+ * Token Resolution for MCP Server
+ * Resolves API tokens with the same priority as the CLI
+ */
+
+import { homedir } from 'os';
+import { join, dirname, parse } from 'path';
+import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+
+/**
+ * Get the path to the global config file
+ */
+function getGlobalConfigPath() {
+  return join(homedir(), '.vizzly', 'config.json');
+}
+
+/**
+ * Load the global configuration
+ */
+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.error('Warning: Global config file is corrupted, ignoring');
+    return {};
+  }
+}
+
+/**
+ * Get authentication tokens from global config
+ */
+async function getAuthTokens() {
+  let config = await loadGlobalConfig();
+
+  if (!config.auth || !config.auth.accessToken) {
+    return null;
+  }
+
+  return config.auth;
+}
+
+/**
+ * Get the access token from global config if available
+ */
+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
+ */
+async function getProjectMapping(directoryPath) {
+  let config = await loadGlobalConfig();
+  if (!config.projects) {
+    return null;
+  }
+
+  // Walk up the directory tree looking for a mapping
+  let currentPath = directoryPath;
+  let { root } = parse(currentPath);
+
+  while (currentPath !== root) {
+    if (config.projects[currentPath]) {
+      return config.projects[currentPath];
+    }
+
+    // Move to parent directory
+    let parentPath = dirname(currentPath);
+    if (parentPath === currentPath) {
+      // We've reached the root
+      break;
+    }
+    currentPath = parentPath;
+  }
+
+  return null;
+}
+
+/**
+ * Resolve token with priority system
+ * Priority order:
+ * 1. Explicitly provided token parameter
+ * 2. Environment variable (VIZZLY_TOKEN)
+ * 3. Project mapping for working directory
+ * 4. User access token from global config
+ *
+ * @param {Object} options - Resolution options
+ * @param {string} options.providedToken - Explicitly provided token (highest priority)
+ * @param {string} options.workingDirectory - Working directory for project mapping lookup
+ * @returns {Promise<string|null>} Resolved token or null
+ */
+export async function resolveToken(options = {}) {
+  let { providedToken, workingDirectory } = options;
+
+  // Priority 1: Explicitly provided token
+  if (providedToken) {
+    return providedToken;
+  }
+
+  // Priority 2: Environment variable
+  if (process.env.VIZZLY_TOKEN) {
+    return process.env.VIZZLY_TOKEN;
+  }
+
+  // Priority 3: Project mapping (if working directory provided)
+  if (workingDirectory) {
+    try {
+      let projectMapping = await getProjectMapping(workingDirectory);
+      if (projectMapping && projectMapping.token) {
+        // Handle both string tokens and token objects
+        let token = typeof projectMapping.token === 'string'
+          ? projectMapping.token
+          : projectMapping.token.token;
+        if (token) {
+          return token;
+        }
+      }
+    } catch (error) {
+      console.error('Warning: Failed to load project mapping:', error.message);
+    }
+  }
+
+  // Priority 4: User access token
+  try {
+    let accessToken = await getAccessToken();
+    if (accessToken) {
+      return accessToken;
+    }
+  } catch (error) {
+    console.error('Warning: Failed to load user access token:', error.message);
+  }
+
+  return null;
+}
+
+/**
+ * Check if the user has valid authentication
+ * @returns {Promise<boolean>} True if user has valid, non-expired authentication
+ */
+export async function hasValidAuth() {
+  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 user information from global config
+ * @returns {Promise<Object|null>} User object or null if not authenticated
+ */
+export async function getUserInfo() {
+  let auth = await getAuthTokens();
+  return auth?.user || null;
+}

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();