@vizzly-testing/cli 0.35.2 → 0.35.3-beta.0

package/README.md

@@ -100,8 +100,8 @@ evidence in one place.
 
 ```bash
 # Cloud context for a build or comparison
-vizzly context build abc123
-vizzly context comparison def456 --json
+vizzly context build abc123 --source cloud
+vizzly context comparison def456 --source cloud --json
 
 # Local workspace context from .vizzly/
 vizzly context build current --source local

package/dist/api/endpoints.js

@@ -30,6 +30,20 @@ export async function getBuild(client, buildId, include = null) {
   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>} Canonical build status bundle
+ */
+export async function getBuildStatus(client, buildId) {
+  return client.request(`/api/sdk/builds/${buildId}/status`);
+}
+
 /**
  * Get builds for a project
  * @param {Object} client - API client
@@ -234,13 +248,20 @@ export async function getComparison(client, comparisonId) {
 }
 
 /**
- * Get build context bundle for agent and reviewer workflows
+ * Get a build context bundle at the detail level the caller can consume.
+ *
+ * Passing detail selection to the API keeps compact callers from downloading
+ * raw Honeydiff geometry by default while preserving the unfiltered endpoint
+ * for raw and full context consumers.
+ *
  * @param {Object} client - API client
  * @param {string} buildId - Build ID
+ * @param {Object} options - Optional query params
  * @returns {Promise<Object>} Build context bundle
  */
-export async function getBuildContext(client, buildId) {
-  return client.request(`/api/sdk/context/builds/${buildId}`);
+export async function getBuildContext(client, buildId, options = {}) {
+  let endpoint = buildEndpointWithParams(`/api/sdk/context/builds/${buildId}`, options);
+  return client.request(endpoint);
 }
 
 /**

package/dist/api/index.js

@@ -16,4 +16,4 @@ export { createApiClient, DEFAULT_API_URL } from './client.js';
 export { buildApiUrl, buildAuthHeader, buildBuildPayload, buildEndpointWithParams, buildQueryParams, buildRequestHeaders, buildScreenshotCheckObject, buildScreenshotPayload, buildScreenshotResolvePayload, buildShaCheckPayload, buildUserAgent, computeSha256, extractErrorBody, findScreenshotBySha, isAuthError, isRateLimited, parseApiError, partitionByShaExistence, shaExists, shouldRetryWithRefresh } from './core.js';
 
 // Endpoint functions
-export { checkShas, createBuild, finalizeBuild, finalizeParallelBuild, getBatchHotspots, getBuild, getBuildContext, getBuilds, getComparison, getComparisonContext, getPreviewInfo, getReviewQueueContext, getScreenshotContext, getScreenshotHotspots, getSimilarFingerprintContext, getTddBaselines, getTokenContext, searchComparisons, updateBuildStatus, uploadPreviewZip, uploadScreenshot } from './endpoints.js';
+export { checkShas, createBuild, finalizeBuild, finalizeParallelBuild, getBatchHotspots, getBuild, getBuildContext, getBuildStatus, getBuilds, getComparison, getComparisonContext, getPreviewInfo, getReviewQueueContext, getScreenshotContext, getScreenshotHotspots, getSimilarFingerprintContext, getTddBaselines, getTokenContext, searchComparisons, updateBuildStatus, uploadPreviewZip, uploadScreenshot } from './endpoints.js';

package/dist/cli.js

@@ -653,12 +653,12 @@ Examples:
 let contextCmd = program.command('context').description('Fetch build and diff context').showHelpAfterError('(Run vizzly context --help for available commands)').showSuggestionAfterError();
 contextCmd.command('build').description('Fetch build context').argument('<build-id>', 'Build ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('--agent', 'Output compact context for LLM agents').option('--full', 'Return the full build context payload with --agent --json').option('--include <items>', 'Add detail to compact agent JSON: screenshots,diffs,comments').addHelpText('after', `
 Examples:
-  $ vizzly context build abc123
+  $ vizzly context build abc123 --source cloud
   $ vizzly context build current --source local
   $ vizzly context build current --source local --agent
-  $ vizzly context build abc123 --agent --json
-  $ vizzly context build abc123 --agent --json --include diffs,comments
-  $ vizzly context build abc123 --agent --json --full
+  $ vizzly context build abc123 --source cloud --agent --json
+  $ vizzly context build abc123 --source cloud --agent --json --include diffs,comments
+  $ vizzly context build abc123 --source cloud --agent --json --full
 `).action(async (buildId, options) => {
   let globalOptions = getGlobalOptions();
   const validationErrors = validateContextBuildOptions(options);
@@ -669,10 +669,10 @@ Examples:
 });
 contextCmd.command('comparison').description('Fetch a comparison context bundle').argument('<comparison-id>', 'Comparison ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('--similar-limit <n>', 'Maximum similar fingerprint matches to return (1-50)', Number).option('--recent-limit <n>', 'Maximum recent same-name comparisons to return (1-50)', Number).option('--window-size <n>', 'Historical hotspot analysis window size (1-50)', Number).addHelpText('after', `
 Examples:
-  $ vizzly context comparison def456
+  $ vizzly context comparison def456 --source cloud
   $ vizzly context comparison def456 --source local
-  $ vizzly context comparison def456 --similar-limit 5 --recent-limit 5
-  $ vizzly context comparison def456 --json
+  $ vizzly context comparison def456 --source cloud --similar-limit 5 --recent-limit 5
+  $ vizzly context comparison def456 --source cloud --json
 `).action(async (comparisonId, options) => {
   let globalOptions = getGlobalOptions();
   const validationErrors = validateContextComparisonOptions(options);
@@ -683,10 +683,10 @@ Examples:
 });
 contextCmd.command('screenshot').description('Fetch screenshot context and historical memory').argument('<name>', 'Screenshot name').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--recent-limit <n>', 'Maximum recent comparisons to return (1-50)', Number).option('--window-size <n>', 'Historical hotspot analysis window size (1-50)', Number).addHelpText('after', `
 Examples:
-  $ vizzly context screenshot Dashboard
+  $ vizzly context screenshot Dashboard --source cloud
   $ vizzly context screenshot Dashboard --source local
-  $ vizzly context screenshot Dashboard --project storybook --org acme
-  $ vizzly context screenshot Dashboard --json
+  $ vizzly context screenshot Dashboard --source cloud --project storybook --org acme
+  $ vizzly context screenshot Dashboard --source cloud --json
 `).action(async (name, options) => {
   let globalOptions = getGlobalOptions();
   const validationErrors = validateContextScreenshotOptions(options);
@@ -697,9 +697,9 @@ Examples:
 });
 contextCmd.command('similar').description('Fetch project-scoped matches for a fingerprint hash').argument('<fingerprint-hash>', 'Fingerprint hash to search for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--limit <n>', 'Maximum matches to return (1-50)', Number).addHelpText('after', `
 Examples:
-  $ vizzly context similar fp-dashboard
-  $ vizzly context similar fp-dashboard --project storybook --org acme
-  $ vizzly context similar fp-dashboard --json
+  $ vizzly context similar fp-dashboard --source cloud
+  $ vizzly context similar fp-dashboard --source cloud --project storybook --org acme
+  $ vizzly context similar fp-dashboard --source cloud --json
 `).action(async (fingerprintHash, options) => {
   let globalOptions = getGlobalOptions();
   const validationErrors = validateContextSimilarOptions(options);
@@ -710,10 +710,10 @@ Examples:
 });
 contextCmd.command('review-queue').description('Fetch pending review context for a project').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--limit <n>', 'Maximum comparisons to return (1-100)', Number).option('--offset <n>', 'Skip first N comparisons', Number).addHelpText('after', `
 Examples:
-  $ vizzly context review-queue --project storybook --org acme
+  $ vizzly context review-queue --source cloud --project storybook --org acme
   $ vizzly context review-queue --source local
-  $ vizzly context review-queue --limit 10
-  $ vizzly context review-queue --json
+  $ vizzly context review-queue --source cloud --limit 10
+  $ vizzly context review-queue --source cloud --json
 `).action(async options => {
   let globalOptions = getGlobalOptions();
   const validationErrors = validateContextReviewQueueOptions(options);

package/dist/commands/comparisons.js

@@ -6,6 +6,7 @@ import { createApiClient as defaultCreateApiClient, getBuild as defaultGetBuild,
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import * as defaultOutput from '../utils/output.js';
 import { createWildcardMatcher } from '../utils/patterns.js';
+import { getComparisonBrowser, getComparisonName, getComparisonResult, getComparisonViewport, getVisualReviewState } from '../utils/visual-context-normalizers.js';
 
 /**
  * Comparisons command - query comparisons with various filters
@@ -73,13 +74,13 @@ export async function comparisonsCommand(options = {}, globalOptions = {}, deps
 
       // Apply status filter if provided
       if (options.status) {
-        comparisons = comparisons.filter(c => c.status === options.status);
+        comparisons = comparisons.filter(comparison => getComparisonResult(comparison) === options.status);
       }
 
       // Apply name filter if provided
       if (options.name) {
         let matchesName = createWildcardMatcher(options.name);
-        comparisons = comparisons.filter(c => matchesName(c.name));
+        comparisons = comparisons.filter(comparison => matchesName(getComparisonName(comparison)));
       }
       if (globalOptions.json) {
         output.data({
@@ -88,9 +89,9 @@ export async function comparisonsCommand(options = {}, globalOptions = {}, deps
           comparisons: comparisons.map(formatComparisonForJson),
           summary: {
             total: comparisons.length,
-            passed: comparisons.filter(c => c.status === 'identical').length,
-            failed: comparisons.filter(c => c.status === 'changed').length,
-            new: comparisons.filter(c => c.status === 'new').length
+            passed: comparisons.filter(comparison => getComparisonResult(comparison) === 'identical').length,
+            failed: comparisons.filter(comparison => getComparisonResult(comparison) === 'changed').length,
+            new: comparisons.filter(comparison => getComparisonResult(comparison) === 'new').length
           }
         });
         output.cleanup();
@@ -164,18 +165,21 @@ function formatComparisonForJson(comparison) {
   let ssimScore = comparison.ssim_score ?? diffImage.ssim_score ?? null;
   let gmsdScore = comparison.gmsd_score ?? diffImage.gmsd_score ?? null;
   let fingerprintHash = comparison.fingerprint_hash || diffImage.fingerprint_hash || null;
-  let hasHoneydiff = clusterMetadata || ssimScore != null || gmsdScore != null || fingerprintHash;
+  let projection = comparison.analysis_projection || comparison.projection || diffImage.analysis_projection || diffImage.projection || null;
+  let diffRegions = comparison.diff_regions ?? diffImage.diff_regions ?? null;
+  let regionCount = comparison.region_count ?? diffImage.region_count ?? projection?.clusters?.count ?? (Array.isArray(diffRegions) ? diffRegions.length : null);
+  let hasHoneydiff = clusterMetadata || ssimScore != null || gmsdScore != null || fingerprintHash || projection || regionCount != null;
   return {
     id: comparison.id,
-    name: comparison.name,
+    name: getComparisonName(comparison),
     status: comparison.status,
+    result: getComparisonResult(comparison),
     diffPercentage: comparison.diff_percentage ?? null,
     approvalStatus: comparison.approval_status,
-    viewport: comparison.viewport_width ? {
-      width: comparison.viewport_width,
-      height: comparison.viewport_height
-    } : null,
-    browser: comparison.browser || null,
+    reviewState: getVisualReviewState(comparison),
+    visualReview: comparison.visual_review || null,
+    viewport: getComparisonViewport(comparison),
+    browser: getComparisonBrowser(comparison),
     urls: {
       baseline: comparison.baseline_screenshot?.original_url || comparison.baseline_original_url || comparison.baseline_screenshot_url || null,
       current: comparison.current_screenshot?.original_url || comparison.current_original_url || comparison.current_screenshot_url || null,
@@ -187,7 +191,9 @@ function formatComparisonForJson(comparison) {
       clusterClassification: clusterMetadata?.classification || null,
       clusterMetadata,
       fingerprintHash,
-      diffRegions: comparison.diff_regions ?? diffImage.diff_regions ?? null,
+      regionCount,
+      projection,
+      diffRegions,
       diffLines: comparison.diff_lines ?? diffImage.diff_lines ?? null,
       fingerprintData: comparison.fingerprint_data ?? diffImage.fingerprint_data ?? null
     } : null,
@@ -202,19 +208,20 @@ function formatComparisonForJson(comparison) {
  * Display a single comparison in detail
  */
 function displayComparison(output, comparison, verbose) {
-  output.header('comparison', comparison.status);
+  let formatted = formatComparisonForJson(comparison);
+  output.header('comparison', formatted.result);
   output.keyValue({
-    Name: comparison.name,
-    Status: comparison.status?.toUpperCase(),
+    Name: formatted.name,
+    Status: formatted.result?.toUpperCase(),
     'Diff %': comparison.diff_percentage != null ? `${(comparison.diff_percentage * 100).toFixed(2)}%` : 'N/A',
-    Approval: comparison.approval_status || 'pending'
+    Review: formatted.reviewState || 'unknown'
   });
   output.blank();
-  if (comparison.viewport_width) {
-    output.labelValue('Viewport', `${comparison.viewport_width}×${comparison.viewport_height}`);
+  if (formatted.viewport) {
+    output.labelValue('Viewport', `${formatted.viewport.width ?? '?'}×${formatted.viewport.height ?? '?'}`);
   }
-  if (comparison.browser) {
-    output.labelValue('Browser', comparison.browser);
+  if (formatted.browser) {
+    output.labelValue('Browser', formatted.browser);
   }
   output.blank();
 
@@ -230,33 +237,33 @@ function displayComparison(output, comparison, verbose) {
   }
 
   // Honeydiff analysis in verbose mode
-  if (verbose) {
-    let clusterMetadata = comparison.cluster_metadata || comparison.diff_image?.cluster_metadata;
-    let ssim = comparison.ssim_score ?? comparison.diff_image?.ssim_score;
-    let gmsd = comparison.gmsd_score ?? comparison.diff_image?.gmsd_score;
-    let fingerprint = comparison.fingerprint_hash || comparison.diff_image?.fingerprint_hash;
-    if (clusterMetadata || ssim != null || gmsd != null || fingerprint) {
+  if (verbose && formatted.honeydiff) {
+    let honeydiff = formatted.honeydiff;
+    if (honeydiff.clusterMetadata || honeydiff.ssimScore != null || honeydiff.gmsdScore != null || honeydiff.fingerprintHash || honeydiff.regionCount != null) {
       output.blank();
-      if (clusterMetadata?.classification) {
-        output.labelValue('Classification', clusterMetadata.classification);
+      if (honeydiff.clusterClassification) {
+        output.labelValue('Classification', honeydiff.clusterClassification);
+      }
+      if (honeydiff.ssimScore != null) {
+        output.labelValue('SSIM', honeydiff.ssimScore.toFixed(4));
       }
-      if (ssim != null) {
-        output.labelValue('SSIM', ssim.toFixed(4));
+      if (honeydiff.gmsdScore != null) {
+        output.labelValue('GMSD', honeydiff.gmsdScore.toFixed(4));
       }
-      if (gmsd != null) {
-        output.labelValue('GMSD', gmsd.toFixed(4));
+      if (honeydiff.fingerprintHash) {
+        output.labelValue('Fingerprint', honeydiff.fingerprintHash);
       }
-      if (fingerprint) {
-        output.labelValue('Fingerprint', fingerprint);
+      if (honeydiff.regionCount != null) {
+        output.labelValue('Regions', String(honeydiff.regionCount));
       }
     }
   }
 
   // URLs in verbose mode
   if (verbose) {
-    let baselineUrl = comparison.baseline_screenshot?.original_url || comparison.baseline_original_url || comparison.baseline_screenshot_url;
-    let currentUrl = comparison.current_screenshot?.original_url || comparison.current_original_url || comparison.current_screenshot_url;
-    let diffUrl = comparison.diff_image?.url || comparison.diff_image_url || comparison.diff_url;
+    let baselineUrl = formatted.urls.baseline;
+    let currentUrl = formatted.urls.current;
+    let diffUrl = formatted.urls.diff;
     if (baselineUrl || currentUrl || diffUrl) {
       output.blank();
       output.labelValue('URLs', '');
@@ -286,9 +293,9 @@ function displayBuildComparisons(output, build, comparisons, verbose) {
   }
 
   // Summary
-  let passed = comparisons.filter(c => c.status === 'identical').length;
-  let failed = comparisons.filter(c => c.status === 'changed').length;
-  let newCount = comparisons.filter(c => c.status === 'new').length;
+  let passed = comparisons.filter(comparison => getComparisonResult(comparison) === 'identical').length;
+  let failed = comparisons.filter(comparison => getComparisonResult(comparison) === 'changed').length;
+  let newCount = comparisons.filter(comparison => getComparisonResult(comparison) === 'new').length;
   let stats = [];
   if (passed > 0) stats.push(`${colors.brand.success(passed)} identical`);
   if (failed > 0) stats.push(`${colors.brand.warning(failed)} changed`);
@@ -298,10 +305,10 @@ function displayBuildComparisons(output, build, comparisons, verbose) {
 
   // List comparisons
   for (let comp of comparisons.slice(0, verbose ? 100 : 20)) {
-    let icon = getStatusIcon(colors, comp.status);
+    let icon = getStatusIcon(colors, getComparisonResult(comp));
     let diffInfo = comp.diff_percentage != null ? colors.dim(` (${(comp.diff_percentage * 100).toFixed(1)}%)`) : '';
     let classification = verbose ? getClassificationLabel(colors, comp.cluster_metadata) : '';
-    output.print(`  ${icon} ${comp.name}${diffInfo}${classification}`);
+    output.print(`  ${icon} ${getComparisonName(comp)}${diffInfo}${classification}`);
   }
   if (comparisons.length > (verbose ? 100 : 20)) {
     output.blank();
@@ -341,9 +348,9 @@ function displaySearchResults(output, comparisons, searchPattern, pagination, ve
       output.print(`    ${colors.dim(group.buildBranch)}`);
     }
     for (let comp of group.comparisons.slice(0, verbose ? 10 : 3)) {
-      let icon = getStatusIcon(colors, comp.status);
+      let icon = getStatusIcon(colors, getComparisonResult(comp));
       let classification = verbose ? getClassificationLabel(colors, comp.cluster_metadata || comp.diff_image?.cluster_metadata) : '';
-      output.print(`      ${icon} ${comp.name}${classification}`);
+      output.print(`      ${icon} ${getComparisonName(comp)}${classification}`);
     }
     if (group.comparisons.length > (verbose ? 10 : 3)) {
       output.print(`      ${colors.dim(`... and ${group.comparisons.length - (verbose ? 10 : 3)} more`)}`);