@vizzly-testing/cli 0.39.1 → 0.39.2

package/dist/domains/baselines/baseline-download.js

@@ -0,0 +1,192 @@
+import { existsSync as defaultExistsSync, writeFileSync as defaultWriteFileSync } from 'node:fs';
+import { fetchWithTimeout as defaultFetchWithTimeout } from '../../shared/fetch-utils.js';
+import { safePath as defaultSafePath } from '../../shared/paths.js';
+import { NetworkError } from '../../shared/vizzly-error.js';
+import { sanitizeScreenshotName as defaultSanitizeScreenshotName } from '../screenshots/screenshot.validations.js';
+import { saveBaselineMetadata as defaultSaveBaselineMetadata } from './baseline-metadata.js';
+
+/** Install one selected cloud build without changing how it was selected. */
+export async function installBaselineBuild({
+  baselineBuild,
+  baselinePath,
+  workingDir,
+  threshold,
+  signatureProperties,
+  existingBaseline,
+  environment,
+  branch,
+  output,
+  fetchWithTimeout = defaultFetchWithTimeout,
+  operations = {}
+}) {
+  let {
+    existsSync = defaultExistsSync,
+    writeFileSync = defaultWriteFileSync,
+    safePath = defaultSafePath,
+    sanitizeScreenshotName = defaultSanitizeScreenshotName,
+    saveBaselineMetadata = defaultSaveBaselineMetadata
+  } = operations;
+  let existingShaMap = new Map();
+  if (existingBaseline) {
+    existingBaseline.screenshots.forEach(screenshot => {
+      if (screenshot.sha256 && screenshot.filename) {
+        existingShaMap.set(screenshot.filename, screenshot.sha256);
+      }
+    });
+  }
+
+  // Download screenshots
+  let downloadedCount = 0;
+  let skippedCount = 0;
+  let errorCount = 0;
+  let batchSize = 5;
+  let screenshotsToProcess = [];
+  for (let screenshot of baselineBuild.screenshots) {
+    let sanitizedName;
+    try {
+      sanitizedName = sanitizeScreenshotName(screenshot.name);
+    } catch (error) {
+      output.warn(`Skipping screenshot with invalid name '${screenshot.name}': ${error.message}`);
+      errorCount++;
+      continue;
+    }
+    let filename = screenshot.filename;
+    if (!filename) {
+      output.warn(`Screenshot ${sanitizedName} has no filename from API - skipping`);
+      errorCount++;
+      continue;
+    }
+    let imagePath = safePath(baselinePath, filename);
+
+    // Check SHA
+    if (existsSync(imagePath) && screenshot.sha256) {
+      let storedSha = existingShaMap.get(filename);
+      if (storedSha === screenshot.sha256) {
+        downloadedCount++;
+        skippedCount++;
+        continue;
+      }
+    }
+    let downloadUrl = screenshot.original_url || screenshot.url;
+    if (!downloadUrl) {
+      output.warn(`Screenshot ${sanitizedName} has no download URL - skipping`);
+      errorCount++;
+      continue;
+    }
+    screenshotsToProcess.push({
+      sanitizedName,
+      imagePath,
+      downloadUrl
+    });
+  }
+
+  // Process downloads in batches
+  if (screenshotsToProcess.length > 0) {
+    output.info(`📥 Downloading ${screenshotsToProcess.length} new/updated screenshots...`);
+    for (let i = 0; i < screenshotsToProcess.length; i += batchSize) {
+      let batch = screenshotsToProcess.slice(i, i + batchSize);
+      let batchNum = Math.floor(i / batchSize) + 1;
+      let totalBatches = Math.ceil(screenshotsToProcess.length / batchSize);
+      output.info(`📦 Processing batch ${batchNum}/${totalBatches}`);
+      let downloadPromises = batch.map(async ({
+        sanitizedName,
+        imagePath,
+        downloadUrl
+      }) => {
+        try {
+          let response = await fetchWithTimeout(downloadUrl);
+          if (!response.ok) {
+            throw new NetworkError(`Failed to download ${sanitizedName}: ${response.statusText}`);
+          }
+          let arrayBuffer = await response.arrayBuffer();
+          let imageBuffer = Buffer.from(arrayBuffer);
+          writeFileSync(imagePath, imageBuffer);
+          return {
+            success: true,
+            name: sanitizedName
+          };
+        } catch (error) {
+          output.warn(`Failed to download ${sanitizedName}: ${error.message}`);
+          return {
+            success: false,
+            name: sanitizedName,
+            error: error.message
+          };
+        }
+      });
+      let batchResults = await Promise.all(downloadPromises);
+      let batchSuccesses = batchResults.filter(r => r.success).length;
+      let batchFailures = batchResults.filter(r => !r.success).length;
+      downloadedCount += batchSuccesses;
+      errorCount += batchFailures;
+    }
+  }
+  if (downloadedCount === 0 && skippedCount === 0) {
+    output.error('No screenshots were successfully downloaded');
+    return null;
+  }
+
+  // Store baseline metadata
+  let baselineData = {
+    buildId: baselineBuild.id,
+    buildName: baselineBuild.name,
+    environment,
+    branch,
+    threshold,
+    signatureProperties,
+    createdAt: new Date().toISOString(),
+    buildInfo: {
+      commitSha: baselineBuild.commit_sha,
+      commitMessage: baselineBuild.commit_message,
+      visual_review: baselineBuild.visual_review || null,
+      completedAt: baselineBuild.completed_at
+    },
+    screenshots: baselineBuild.screenshots.filter(s => s.filename).map(s => ({
+      name: sanitizeScreenshotName(s.name),
+      originalName: s.name,
+      sha256: s.sha256,
+      id: s.id,
+      filename: s.filename,
+      path: safePath(baselinePath, s.filename),
+      browser: s.browser,
+      viewport_width: s.viewport_width,
+      originalUrl: s.original_url,
+      fileSize: s.file_size_bytes,
+      dimensions: {
+        width: s.width,
+        height: s.height
+      }
+    }))
+  };
+  saveBaselineMetadata(baselinePath, baselineData);
+
+  // Save baseline build metadata for MCP plugin
+  let baselineMetadataPath = safePath(workingDir, '.vizzly', 'baseline-metadata.json');
+  writeFileSync(baselineMetadataPath, JSON.stringify({
+    buildId: baselineBuild.id,
+    buildName: baselineBuild.name,
+    branch,
+    environment,
+    commitSha: baselineBuild.commit_sha,
+    commitMessage: baselineBuild.commit_message,
+    visual_review: baselineBuild.visual_review || null,
+    completedAt: baselineBuild.completed_at,
+    downloadedAt: new Date().toISOString()
+  }, null, 2));
+
+  // Summary
+  let actualDownloads = downloadedCount - skippedCount;
+  if (skippedCount > 0) {
+    if (actualDownloads === 0) {
+      output.info(`All ${skippedCount} baselines up-to-date`);
+    } else {
+      output.info(`Downloaded ${actualDownloads} new screenshots, ${skippedCount} already up-to-date`);
+    }
+  } else {
+    output.info(`Downloaded ${downloadedCount}/${baselineBuild.screenshots.length} screenshots successfully`);
+  }
+  if (errorCount > 0) {
+    output.warn(`${errorCount} screenshots failed to download`);
+  }
+  return baselineData;
+}

package/dist/domains/baselines/baseline-write.js

@@ -0,0 +1,22 @@
+import { writeFileSync as defaultWriteFileSync } from 'node:fs';
+import { createEmptyBaselineMetadata as defaultCreateEmptyBaselineMetadata, upsertScreenshotInMetadata as defaultUpsertScreenshotInMetadata } from './baseline-metadata.js';
+
+/**
+ * Write one image and update its baseline record. The caller commits metadata
+ * after a single approval or after its full bulk update has finished.
+ */
+export function writeBaselineScreenshot({
+  imageBuffer,
+  screenshot,
+  metadata,
+  baselineOptions
+}, {
+  writeFileSync = defaultWriteFileSync,
+  createEmptyBaselineMetadata = defaultCreateEmptyBaselineMetadata,
+  upsertScreenshotInMetadata = defaultUpsertScreenshotInMetadata
+} = {}) {
+  writeFileSync(screenshot.path, imageBuffer);
+  let baselineData = metadata || createEmptyBaselineMetadata(baselineOptions);
+  upsertScreenshotInMetadata(baselineData, screenshot, screenshot.signature);
+  return baselineData;
+}

package/dist/{server/routers/baseline.js → domains/baselines/baseline.routes.js}

@@ -3,9 +3,9 @@
  * Handles baseline management (accept, accept-all, reset)
  */
 
-import * as output from '../../utils/output.js';
-import { parseJsonBody } from '../middleware/json-parser.js';
-import { sendError, sendServiceUnavailable, sendSuccess } from '../middleware/response.js';
+import { parseJsonBody } from '../../adapters/http/middleware/json-parser.js';
+import { sendError, sendServiceUnavailable, sendSuccess } from '../../adapters/http/middleware/response.js';
+import * as output from '../../shared/output.js';
 function sendBaselineUnavailable(res) {
   sendError(res, 400, 'Baseline management not available');
 }

package/dist/{tdd/services/baseline-manager.js → domains/baselines/baseline.service.js}

@@ -5,7 +5,7 @@
  * of baseline storage without any network operations.
  */
 
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 /**
@@ -148,42 +148,4 @@ export function getCurrentPath(currentPath, filename) {
  */
 export function getDiffPath(diffPath, filename) {
   return join(diffPath, filename);
-}
-
-/**
- * Promote current screenshot to baseline (accept as new baseline)
- *
- * @param {string} currentPath - Path to current screenshots directory
- * @param {string} baselinePath - Path to baselines directory
- * @param {string} filename - Filename
- */
-export function promoteCurrentToBaseline(currentPath, baselinePath, filename) {
-  let currentFile = join(currentPath, filename);
-  let baselineFile = join(baselinePath, filename);
-  if (!existsSync(currentFile)) {
-    throw new Error(`Current screenshot not found: ${currentFile}`);
-  }
-  copyFileSync(currentFile, baselineFile);
-}
-
-/**
- * Read baseline image
- *
- * @param {string} baselinePath - Path to baselines directory
- * @param {string} filename - Filename
- * @returns {Buffer}
- */
-export function readBaseline(baselinePath, filename) {
-  return readFileSync(join(baselinePath, filename));
-}
-
-/**
- * Read current screenshot
- *
- * @param {string} currentPath - Path to current screenshots directory
- * @param {string} filename - Filename
- * @returns {Buffer}
- */
-export function readCurrent(currentPath, filename) {
-  return readFileSync(join(currentPath, filename));
 }

package/dist/{commands/baselines.js → domains/baselines/baselines.commands.js}

@@ -4,9 +4,9 @@
 
 import { existsSync as defaultExistsSync, readdirSync as defaultReaddirSync, statSync as defaultStatSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { loadBaselineMetadata as defaultLoadBaselineMetadata } from '../tdd/metadata/baseline-metadata.js';
-import * as defaultOutput from '../utils/output.js';
-import { createWildcardMatcher } from '../utils/patterns.js';
+import * as defaultOutput from '../../shared/output.js';
+import { createWildcardMatcher } from '../../shared/patterns.js';
+import { loadBaselineMetadata as defaultLoadBaselineMetadata } from './baseline-metadata.js';
 
 /**
  * Extract filename from a path

package/dist/domains/baselines/cloud-baselines.js

@@ -0,0 +1,9 @@
+/**
+ * Get TDD baselines for a build
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @returns {Promise<Object>} { build, screenshots, signatureProperties }
+ */
+export async function getTddBaselines(client, buildId) {
+  return client.request(`/api/sdk/builds/${buildId}/tdd-baselines`);
+}

package/dist/domains/baselines/cloud-baselines.routes.js

@@ -0,0 +1,42 @@
+import { parseJsonBody } from '../../adapters/http/middleware/json-parser.js';
+import { sendError, sendSuccess } from '../../adapters/http/middleware/response.js';
+import * as output from '../../shared/output.js';
+export function createCloudBaselinesRouter({
+  authService
+}) {
+  return async function handleCloudBaselinesRoute(req, res, pathname) {
+    if (req.method !== 'POST' || pathname !== '/api/cloud/baselines/download') {
+      return false;
+    }
+    try {
+      let body = await parseJsonBody(req);
+      let {
+        buildId,
+        screenshotNames
+      } = body;
+      if (!buildId) {
+        sendError(res, 400, 'buildId is required');
+        return true;
+      }
+      let response = await authService.authenticatedRequest('/api/cli/baselines/download', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          buildId,
+          screenshotNames
+        })
+      });
+      sendSuccess(res, {
+        success: true,
+        message: `Baselines downloaded from build ${buildId}`,
+        ...response
+      });
+    } catch (error) {
+      output.error('Error downloading baselines from cloud:', error);
+      sendError(res, 500, error.message);
+    }
+    return true;
+  };
+}

package/dist/domains/builds/build.normalizers.js

@@ -0,0 +1,35 @@
+import { getVisualReviewState } from '../context/context.normalizers.js';
+export function normalizeBuildStatus(buildStatus) {
+  return buildStatus.build;
+}
+
+/**
+ * Read the processing counts from the status response.
+ *
+ * @param {Object} status - Status response.
+ * @returns {Object} API-provided processing facts.
+ */
+export function getProcessingStatus(status = {}) {
+  return status.processing;
+}
+
+/**
+ * Read comparison totals without deriving them from screenshot counts.
+ *
+ * @param {Object} status - Status response.
+ * @returns {Object} API-provided comparison facts.
+ */
+export function getComparisonStatus(status = {}) {
+  return status.comparisons;
+}
+
+/**
+ * Read the build review state without mixing it with processing status.
+ *
+ * @param {Object} status - Status response.
+ * @returns {string|null} API-provided review state when available.
+ */
+export function getBuildReviewState(status = {}) {
+  let build = normalizeBuildStatus(status);
+  return getVisualReviewState(build);
+}

package/dist/domains/builds/build.serializers.js

@@ -0,0 +1,164 @@
+import { getComparisonStatus, getProcessingStatus, normalizeBuildStatus } from './build.normalizers.js';
+
+/**
+ * Build payload for build creation
+ * @param {Object} options - Build options
+ * @returns {Object} Build creation payload
+ */
+export function buildBuildPayload(options) {
+  let payload = {
+    name: options.name || options.buildName,
+    branch: options.branch,
+    environment: options.environment
+  };
+  if (options.commit || options.commit_sha) {
+    payload.commit_sha = options.commit || options.commit_sha;
+  }
+  if (options.message || options.commit_message) {
+    payload.commit_message = options.message || options.commit_message;
+  }
+  if (options.commit_author_name) {
+    payload.commit_author_name = options.commit_author_name;
+  }
+  if (options.commit_author_email) {
+    payload.commit_author_email = options.commit_author_email;
+  }
+  if (options.pullRequestNumber || options.github_pull_request_number) {
+    payload.github_pull_request_number = options.pullRequestNumber || options.github_pull_request_number;
+  }
+  if (options.parallelId || options.parallel_id) {
+    payload.parallel_id = options.parallelId || options.parallel_id;
+  }
+  if (options.threshold != null) {
+    payload.threshold = options.threshold;
+  }
+  if (options.metadata) {
+    payload.metadata = options.metadata;
+  }
+  return payload;
+}
+
+/**
+ * Format a build for JSON output
+ */
+export function formatBuildForJson(build, includeComparisons = false) {
+  let result = {
+    id: build.id,
+    name: build.name,
+    status: build.status,
+    branch: build.branch,
+    commit: build.commit_sha,
+    commitMessage: build.commit_message,
+    environment: build.environment,
+    screenshotCount: build.screenshot_count || 0,
+    comparisons: {
+      total: build.total_comparisons || 0,
+      new: build.new_comparisons || 0,
+      changed: build.changed_comparisons || 0,
+      identical: build.identical_comparisons || 0
+    },
+    visual_review: build.visual_review || null,
+    createdAt: build.created_at,
+    completedAt: build.completed_at
+  };
+  if (includeComparisons && build.comparisons) {
+    result.comparisonDetails = build.comparisons.map(c => {
+      let diffUrl = c.diff_image?.url || c.diff_image_url || c.diff_url || null;
+      let diffImage = c.diff_image || {};
+      let clusterMetadata = c.cluster_metadata || diffImage.cluster_metadata || null;
+      let ssimScore = c.ssim_score ?? diffImage.ssim_score ?? null;
+      let gmsdScore = c.gmsd_score ?? diffImage.gmsd_score ?? null;
+      let fingerprintHash = c.fingerprint_hash || diffImage.fingerprint_hash || null;
+      let hasHoneydiff = clusterMetadata || ssimScore != null || gmsdScore != null || fingerprintHash;
+      return {
+        id: c.id,
+        name: c.name || c.current_name,
+        status: c.status,
+        diffPercentage: c.diff_percentage,
+        visual_review: c.visual_review || null,
+        urls: {
+          baseline: c.baseline_screenshot?.original_url || c.baseline_original_url || c.baseline_screenshot_url || null,
+          current: c.current_screenshot?.original_url || c.current_original_url || c.current_screenshot_url || null,
+          diff: diffUrl
+        },
+        honeydiff: hasHoneydiff ? {
+          ssimScore,
+          gmsdScore,
+          clusterClassification: clusterMetadata?.classification || null,
+          clusterMetadata,
+          fingerprintHash,
+          diffRegions: c.diff_regions ?? diffImage.diff_regions ?? null
+        } : null
+      };
+    });
+  }
+  return result;
+}
+
+/**
+ * Give agents concrete paths from lifecycle status into visual evidence.
+ *
+ * @param {Object} build - Build record from the status response.
+ * @returns {{label: string, command: string}[]} Executable CLI commands.
+ */
+export function createStatusSuggestedCommands(build = {}) {
+  if (!build.id) {
+    return [];
+  }
+  return [{
+    label: 'Discover build context API',
+    command: 'vizzly api schema sdk.getBuildContext --json'
+  }, {
+    label: 'List comparisons',
+    command: `vizzly --json comparisons --build ${build.id}`
+  }];
+}
+
+/**
+ * Every lifecycle, processing, comparison, and review value comes directly
+ * from the API.
+ *
+ * @param {Object} status - Status response.
+ * @param {Object|null} previewInfo - Optional preview response.
+ * @returns {Object} Machine-readable status payload.
+ */
+export function createStatusData(status, previewInfo = null) {
+  let build = normalizeBuildStatus(status);
+  let processing = getProcessingStatus(status);
+  let comparisons = getComparisonStatus(status);
+  return {
+    resource: status.resource,
+    schemaVersion: status.schema_version,
+    buildId: build.id,
+    status: build.status,
+    conclusion: status.conclusion,
+    name: build.name,
+    createdAt: build.created_at,
+    updatedAt: build.updated_at,
+    completedAt: build.completed_at,
+    environment: build.environment,
+    branch: build.branch,
+    commit: build.commit_sha,
+    commitMessage: build.commit_message,
+    screenshotsTotal: processing.total,
+    processing,
+    comparisonsTotal: comparisons.total,
+    comparisons,
+    newComparisons: comparisons.new,
+    changedComparisons: comparisons.changed,
+    identicalComparisons: comparisons.identical,
+    visual_review: build.visual_review || null,
+    executionTime: build.execution_time_ms,
+    isBaseline: build.is_baseline,
+    userAgent: build.user_agent,
+    scope: status.scope,
+    links: status.links,
+    suggestedCommands: createStatusSuggestedCommands(build),
+    preview: previewInfo ? {
+      url: previewInfo.preview_url,
+      status: previewInfo.status,
+      fileCount: previewInfo.file_count,
+      expiresAt: previewInfo.expires_at
+    } : null
+  };
+}

package/dist/domains/builds/build.service.js

@@ -0,0 +1,119 @@
+import { buildEndpointWithParams, buildQueryParams } from '../../shared/cloud-protocol.js';
+import { buildBuildPayload } from './build.serializers.js';
+
+/**
+ * Get build information
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @param {string|null} include - Optional include parameter (e.g., 'screenshots')
+ * @returns {Promise<Object>} Build data
+ */
+export async function getBuild(client, buildId, include = null) {
+  let endpoint = `/api/sdk/builds/${buildId}`;
+  if (include) {
+    endpoint = buildEndpointWithParams(endpoint, {
+      include
+    });
+  }
+  return client.request(endpoint);
+}
+
+/**
+ * Get the server-owned build processing and review status.
+ *
+ * This endpoint keeps processing, comparison, and review counts separate so
+ * callers do not have to reconstruct lifecycle state from legacy build fields.
+ *
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @returns {Promise<Object>} Build status response
+ */
+export async function getBuildStatus(client, buildId) {
+  return client.request(`/api/sdk/builds/${buildId}/status`);
+}
+
+/**
+ * Get builds for a project
+ * @param {Object} client - API client
+ * @param {Object} filters - Filter options
+ * @returns {Promise<Array>} List of builds
+ */
+export async function getBuilds(client, filters = {}) {
+  let query = buildQueryParams(filters);
+  let endpoint = `/api/sdk/builds${query ? `?${query}` : ''}`;
+  return client.request(endpoint);
+}
+
+/**
+ * Create a new build
+ * @param {Object} client - API client
+ * @param {Object} metadata - Build metadata
+ * @returns {Promise<Object>} Created build data
+ */
+export async function createBuild(client, metadata) {
+  let payload = buildBuildPayload(metadata);
+  return client.request('/api/sdk/builds', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      build: payload
+    })
+  });
+}
+
+/**
+ * Update build status
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @param {string} status - Build status (pending|running|completed|failed)
+ * @param {number|null} [executionTimeMs=null] - Execution time in milliseconds
+ * @param {string} [failureReason] - Explanation sent only for a failed build
+ * @returns {Promise<Object>} Updated build data
+ */
+export async function updateBuildStatus(client, buildId, status, executionTimeMs = null, failureReason) {
+  let body = {
+    status
+  };
+  if (status === 'failed' && failureReason) body.failureReason = failureReason;
+  if (executionTimeMs != null) {
+    body.executionTimeMs = executionTimeMs;
+  }
+  return client.request(`/api/sdk/builds/${buildId}/status`, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(body)
+  });
+}
+
+/**
+ * Mark a build completed or failed, with an optional failure explanation.
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @param {boolean} [success=true] - Whether tests and uploads succeeded
+ * @param {number|null} [executionTimeMs=null] - Execution time in milliseconds
+ * @param {string} [failureReason] - Explanation sent only for a failed build
+ * @returns {Promise<Object>} Finalized build data
+ */
+export async function finalizeBuild(client, buildId, success = true, executionTimeMs = null, failureReason) {
+  let status = success ? 'completed' : 'failed';
+  return updateBuildStatus(client, buildId, status, executionTimeMs, failureReason);
+}
+
+/**
+ * Finalize a parallel build
+ * @param {Object} client - API client
+ * @param {string} parallelId - Parallel ID to finalize
+ * @returns {Promise<Object>} Finalization result
+ */
+export async function finalizeParallelBuild(client, parallelId) {
+  return client.request(`/api/sdk/parallel/${parallelId}/finalize`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    }
+  });
+}