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

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 --agent --json
 
 # Local workspace context from .vizzly/
 vizzly context build current --source local
@@ -110,9 +110,12 @@ vizzly context screenshot build-detail-screenshots --source local --json
 vizzly context review-queue --source local --json
 ```
 
-`--json` is the durable automation path. `--agent` gives a compact handoff for
-prompt assembly. Add `--full` when you need the whole payload, or
-`--include screenshots,diffs,comments` when compact JSON needs selected detail.
+`--json` is the durable automation path. `--agent` gives you the compact API
+handoff for prompt assembly. Build handoffs contain up to 10 records; use the
+exact next-page command returned in `suggested_commands` to continue safely.
+That command carries the API's opaque `--cursor`. Add
+`--include diffs` for raw diff diagnostics, or `--full` when you need the whole
+payload.
 
 Local context is read-only and file-backed. It reads your existing `.vizzly`
 workspace state from TDD runs, including screenshots, diffs, and saved hotspot

package/dist/api/client.js

@@ -18,6 +18,11 @@ function isProjectToken(token) {
   return typeof token === 'string' && token.startsWith('vzt_');
 }
 
+/** Prefer the transport cause because Node's top-level fetch message is generic. */
+function getNetworkFailureReason(error) {
+  return error?.cause?.code || error?.cause?.message || error?.message || 'request failed';
+}
+
 /**
  * Create an API client with the given configuration
  *
@@ -58,10 +63,19 @@ export function createApiClient(options = {}) {
       contentType: fetchOptions.headers?.['Content-Type'],
       extra: fetchOptions.headers || {}
     });
-    let response = await fetch(url, {
-      ...fetchOptions,
-      headers
-    });
+    let response;
+    try {
+      response = await fetch(url, {
+        ...fetchOptions,
+        headers
+      });
+    } catch (error) {
+      let apiOrigin = new URL(url).origin;
+      let reason = getNetworkFailureReason(error);
+      throw new VizzlyError(`Unable to reach Vizzly at ${apiOrigin}: ${reason}`, 'NETWORK_ERROR', {
+        apiOrigin
+      });
+    }
     if (!response.ok) {
       let errorBody = await extractErrorBody(response);
 
@@ -82,7 +96,8 @@ export function createApiClient(options = {}) {
       // Other errors
       let error = parseApiError(response.status, errorBody, url);
       throw new VizzlyError(error.message, error.code, {
-        status: error.status
+        status: error.status,
+        details: error.details
       });
     }
     return response.json();

package/dist/api/core.js

@@ -232,8 +232,21 @@ export function shouldRetryWithRefresh(status, isRetry, hasRefreshToken) {
  */
 export function parseApiError(status, body, url) {
   let message = `API request failed: ${status}`;
+  let responseDetails = null;
+  let responseCode = null;
+  let responseMessage = body;
   if (body) {
-    message += ` - ${body}`;
+    try {
+      let parsedBody = JSON.parse(body);
+      responseDetails = parsedBody.details ?? null;
+      responseCode = parsedBody.code ?? parsedBody.details?.code ?? null;
+      responseMessage = parsedBody.error ?? parsedBody.message ?? body;
+    } catch {
+      // Plain-text API errors remain valid and are surfaced unchanged.
+    }
+  }
+  if (responseMessage) {
+    message += ` - ${responseMessage}`;
   }
   message += ` (URL: ${url})`;
   let code = 'API_ERROR';
@@ -244,8 +257,9 @@ export function parseApiError(status, body, url) {
   if (status >= 500) code = 'SERVER_ERROR';
   return {
     message,
-    code,
-    status
+    code: responseCode || code,
+    status,
+    details: responseDetails
   };
 }
 

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

@@ -3,17 +3,17 @@ import 'dotenv/config';
 import { existsSync, statSync } from 'node:fs';
 import { Option, program } from 'commander';
 import { apiCommand, validateApiOptions } from './commands/api.js';
-import { baselinesCommand, validateBaselinesOptions } from './commands/baselines.js';
+import { baselinesCommand } from './commands/baselines.js';
 import { buildsCommand, validateBuildsOptions } from './commands/builds.js';
 import { comparisonsCommand, validateComparisonsOptions } from './commands/comparisons.js';
-import { configCommand, validateConfigOptions } from './commands/config-cmd.js';
+import { configCommand } from './commands/config-cmd.js';
 import { contextBuildCommand, contextComparisonCommand, contextReviewQueueCommand, contextScreenshotCommand, contextSimilarCommand, validateContextBuildOptions, validateContextComparisonOptions, validateContextReviewQueueOptions, validateContextScreenshotOptions, validateContextSimilarOptions } from './commands/context.js';
-import { doctorCommand, validateDoctorOptions } from './commands/doctor.js';
+import { doctorCommand } from './commands/doctor.js';
 import { finalizeCommand, validateFinalizeOptions } from './commands/finalize.js';
 import { init } from './commands/init.js';
-import { loginCommand, validateLoginOptions } from './commands/login.js';
-import { logoutCommand, validateLogoutOptions } from './commands/logout.js';
-import { orgsCommand, validateOrgsOptions } from './commands/orgs.js';
+import { loginCommand } from './commands/login.js';
+import { logoutCommand } from './commands/logout.js';
+import { orgsCommand } from './commands/orgs.js';
 import { previewCommand, validatePreviewOptions } from './commands/preview.js';
 import { projectLinkCommand, validateProjectLinkOptions } from './commands/project.js';
 import { projectsCommand, validateProjectsOptions } from './commands/projects.js';
@@ -23,7 +23,7 @@ import { statusCommand, validateStatusOptions } from './commands/status.js';
 import { tddCommand, validateTddOptions } from './commands/tdd.js';
 import { runDaemonChild, tddListCommand, tddStartCommand, tddStatusCommand, tddStopCommand, validateTddStartOptions } from './commands/tdd-daemon.js';
 import { uploadCommand, validateUploadOptions } from './commands/upload.js';
-import { validateWhoamiOptions, whoamiCommand } from './commands/whoami.js';
+import { whoamiCommand } from './commands/whoami.js';
 import { createPluginServices } from './plugin-api.js';
 import { loadPlugins } from './plugin-loader.js';
 import { createServices } from './services/index.js';
@@ -651,14 +651,14 @@ Examples:
   await comparisonsCommand(options, globalOptions);
 });
 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', `
+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 instead of compact context').option('--cursor <cursor>', 'Continue compact evidence from an opaque API cursor').option('--include <items>', 'Add raw diff diagnostics to compact context: diffs').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
+  $ vizzly context build abc123 --source cloud --agent --json --full
 `).action(async (buildId, options) => {
   let globalOptions = getGlobalOptions();
   const validationErrors = validateContextBuildOptions(options);
@@ -667,12 +667,12 @@ Examples:
   }
   await contextBuildCommand(buildId, options, globalOptions);
 });
-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', `
+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('--agent', 'Output compact context for LLM agents').option('--full', 'Return the full comparison context instead of compact context').option('--cursor <cursor>', 'Continue compact history from an opaque API cursor').option('--include <items>', 'Add detail to compact context: diffs').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 --json
+  $ vizzly context comparison def456 --source cloud --agent --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);
@@ -724,12 +724,6 @@ Examples:
 });
 program.command('config').description('Display current configuration').argument('[key]', 'Specific config key to get (dot notation, e.g., comparison.threshold)').action(async (key, options) => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateConfigOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await configCommand(key, options, globalOptions);
 });
 program.command('baselines').description('List and query local TDD baselines').option('--name <pattern>', 'Filter baselines by name (supports wildcards)').option('--info <name>', 'Get detailed info for a specific baseline').addHelpText('after', `
@@ -742,12 +736,6 @@ Examples:
 Note: Baselines are stored locally in .vizzly/baselines/ during TDD mode.
 `).action(async options => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateBaselinesOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await baselinesCommand(options, globalOptions);
 });
 program.command('api').description('Make raw API requests (for power users)').argument('<endpoint>', 'API endpoint (e.g., /api/sdk/builds)').option('-X, --method <method>', 'HTTP method (GET or POST for approve/reject/comment)', 'GET').option('-d, --data <json>', 'Request body (JSON)').option('-H, --header <header>', 'Add header (key:value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).option('-q, --query <param>', 'Add query param (key=value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).addHelpText('after', `
@@ -833,10 +821,6 @@ Note: Shows organizations from your user account (via vizzly login)
 or the single organization for a project token.
 `).action(async options => {
   let globalOptions = getGlobalOptions();
-  const validationErrors = validateOrgsOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await orgsCommand(options, globalOptions);
 });
 program.command('projects').description('List projects you have access to').option('--org <slug>', 'Filter by organization slug').option('--limit <n>', 'Maximum results to return (1-250)', Number, 50).option('--offset <n>', 'Skip first N results', Number, 0).addHelpText('after', `
@@ -910,42 +894,18 @@ program.command('preview').description('Upload static files as a preview for a b
 });
 program.command('doctor').description('Run diagnostics to check your environment and configuration').option('--api', 'Include API connectivity checks').action(async options => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateDoctorOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await doctorCommand(options, globalOptions);
 });
 program.command('login').description('Authenticate with your Vizzly account').option('--api-url <url>', 'API URL override').action(async options => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateLoginOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await loginCommand(options, globalOptions);
 });
 program.command('logout').description('Clear stored authentication tokens').option('--api-url <url>', 'API URL override').action(async options => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateLogoutOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   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 => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateWhoamiOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await whoamiCommand(options, globalOptions);
 });
 

package/dist/commands/baselines.js

@@ -286,11 +286,4 @@ export function formatBytes(bytes) {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
-
-/**
- * Validate baselines command options
- */
-export function validateBaselinesOptions() {
-  return [];
 }

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`)}`);

package/dist/commands/config-cmd.js

@@ -163,11 +163,4 @@ function getNestedValue(obj, path) {
     current = current[part];
   }
   return current;
-}
-
-/**
- * Validate config command options
- */
-export function validateConfigOptions() {
-  return [];
 }