@vizzly-testing/cli 0.30.0 → 0.32.0

package/dist/commands/context.js

@@ -7,12 +7,16 @@ import { createLocalWorkspaceContextProvider as defaultCreateLocalWorkspaceConte
 import { resolveContextSource as defaultResolveContextSource } from '../context/provider-resolver.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import * as defaultOutput from '../utils/output.js';
+import { readSession as defaultReadSession } from '../utils/session.js';
 function buildAuthErrorMessage() {
-  return 'API token required. Use --token, set VIZZLY_TOKEN, or run "vizzly login"';
+  return 'Authentication required. Use --token, set VIZZLY_TOKEN, run "vizzly login", or link a project.';
 }
 function buildSourceErrorMessage() {
   return '--source must be one of: auto, cloud, local';
 }
+function buildIncludeErrorMessage() {
+  return '--include must contain only: screenshots, diffs, comments';
+}
 function validateLimitRange(value, flagName, {
   min = 1,
   max
@@ -21,7 +25,7 @@ function validateLimitRange(value, flagName, {
     return [];
   }
   if (!Number.isInteger(value) || value < min || value > max) {
-    return [`${flagName} must be a number between ${min} and ${max}`];
+    return [`${flagName} must be an integer between ${min} and ${max}`];
   }
   return [];
 }
@@ -30,7 +34,7 @@ function validateOffset(value) {
     return [];
   }
   if (!Number.isInteger(value) || value < 0) {
-    return ['--offset must be a non-negative number'];
+    return ['--offset must be a non-negative integer'];
   }
   return [];
 }
@@ -43,6 +47,18 @@ function validateSourceOption(value) {
   }
   return [];
 }
+function parseIncludeOption(value) {
+  if (!value) {
+    return [];
+  }
+  let rawItems = Array.isArray(value) ? value : String(value).split(',');
+  return rawItems.map(item => item.trim()).filter(Boolean);
+}
+function validateIncludeOption(value) {
+  let allowed = new Set(['screenshots', 'diffs', 'comments']);
+  let invalid = parseIncludeOption(value).filter(item => !allowed.has(item));
+  return invalid.length > 0 ? [buildIncludeErrorMessage()] : [];
+}
 function validateScopedProjectOptions(options = {}) {
   let errors = [];
   if (options.org && !options.project) {
@@ -50,10 +66,13 @@ function validateScopedProjectOptions(options = {}) {
   }
   return errors;
 }
+function hasExplicitCloudScope(options = {}, config = {}) {
+  return Boolean(options.org || options.project || config.linkedProject?.organizationSlug || config.linkedProject?.projectSlug);
+}
 function createClient(config, createApiClient) {
   return createApiClient({
     baseUrl: config.apiUrl,
-    token: config.apiKey,
+    token: config.apiKey || config.userToken,
     command: 'context'
   });
 }
@@ -69,7 +88,7 @@ async function loadContextConfig(globalOptions, options, deps) {
     ...options
   };
   let config = await loadConfig(globalOptions.config, allOptions);
-  if (requireApiKey && !config.apiKey) {
+  if (requireApiKey && !config.apiKey && !config.userToken) {
     output.error(buildAuthErrorMessage());
     output.cleanup();
     exit(1);
@@ -111,6 +130,23 @@ function buildLocalFingerprintCapabilityError() {
   error.code = 'LOCAL_WORKSPACE_CONTEXT';
   return error;
 }
+function resolveBuildContextId(buildId, runtime, deps = {}) {
+  let {
+    readSession = defaultReadSession
+  } = deps;
+  if (buildId !== 'current' || runtime.source !== 'cloud') {
+    return buildId;
+  }
+  let session = readSession({
+    cwd: runtime.projectRoot
+  });
+  if (session?.buildId && !session.expired) {
+    return session.buildId;
+  }
+  let error = new Error('No current cloud build found. Run "vizzly run" first, or pass a build ID.');
+  error.code = 'NO_CURRENT_CLOUD_BUILD';
+  throw error;
+}
 function shouldExplainLocalSimilarityGap(requestedSource, command, localProvider) {
   return requestedSource === 'auto' && command === 'similar' && localProvider.isAvailable();
 }
@@ -136,11 +172,12 @@ async function loadContextRuntime(command, target, globalOptions, options, deps
     requestedSource,
     command,
     target,
-    projectRoot
+    projectRoot,
+    hasCloudScope: hasExplicitCloudScope(options, config)
   }, {
     createLocalWorkspaceContextProvider
   });
-  if (source === 'cloud' && !config.apiKey) {
+  if (source === 'cloud' && !config.apiKey && !config.userToken) {
     if (shouldExplainLocalSimilarityGap(requestedSource, command, localProvider)) {
       throw buildLocalFingerprintCapabilityError();
     }
@@ -183,6 +220,189 @@ function getStatusTone(colors, status) {
 function getComparisonDisplayState(comparison = {}) {
   return comparison.result || comparison.status || 'unknown';
 }
+function isChangedComparison(comparison = {}) {
+  return ['changed', 'failed', 'pending'].includes(getComparisonDisplayState(comparison));
+}
+function isNewComparison(comparison = {}) {
+  return getComparisonDisplayState(comparison) === 'new';
+}
+function getComparisonName(comparison = {}) {
+  return comparison.screenshot_name || comparison.screenshot?.name || comparison.name || comparison.id || 'unknown screenshot';
+}
+function getComparisonDiffPercentage(comparison = {}) {
+  return comparison.diff?.percentage ?? comparison.diff_percentage ?? null;
+}
+function getComparisonFingerprint(comparison = {}) {
+  return comparison.diff?.fingerprint_hash || comparison.analysis?.fingerprint_hash || null;
+}
+function getComparisonDiffImageUrl(comparison = {}) {
+  return comparison.diff?.image_url || comparison.analysis?.diff_image_url || null;
+}
+function getComparisonRegionCount(comparison = {}) {
+  let regions = comparison.diff?.regions || comparison.analysis?.diff_regions;
+  return Array.isArray(regions) ? regions.length : 0;
+}
+function getComparisonScreenshot(comparison = {}) {
+  return comparison.screenshot || {};
+}
+function getComparisonBaseline(comparison = {}) {
+  return comparison.baseline || comparison.screenshot?.baseline || {};
+}
+function buildCompactDiff(comparison = {}, includeDiffs = false) {
+  let diff = comparison.diff || comparison.analysis || {};
+  let compact = {
+    percentage: getComparisonDiffPercentage(comparison),
+    changed_pixels: diff.changed_pixels ?? comparison.changed_pixels ?? null,
+    total_pixels: diff.total_pixels ?? comparison.total_pixels ?? null,
+    threshold: diff.threshold ?? comparison.threshold ?? null,
+    fingerprint_hash: getComparisonFingerprint(comparison),
+    region_count: getComparisonRegionCount(comparison),
+    image_url: getComparisonDiffImageUrl(comparison)
+  };
+  if (includeDiffs) {
+    compact.regions = diff.regions || diff.diff_regions || [];
+    compact.cluster_metadata = diff.cluster_metadata || null;
+    compact.ssim_score = diff.ssim_score ?? null;
+    compact.gmsd_score = diff.gmsd_score ?? null;
+    compact.diff_lines = diff.diff_lines || [];
+  }
+  return compact;
+}
+function buildCompactComparison(comparison = {}, {
+  includeDiffs = false
+} = {}) {
+  let screenshot = getComparisonScreenshot(comparison);
+  let baseline = getComparisonBaseline(comparison);
+  return {
+    id: comparison.id || null,
+    name: getComparisonName(comparison),
+    result: getComparisonDisplayState(comparison),
+    approval_status: comparison.approval_status || null,
+    needs_review: Boolean(comparison.needs_review),
+    is_flaky: Boolean(comparison.is_flaky),
+    screenshot: {
+      id: screenshot.id || null,
+      url: screenshot.url || screenshot.original_url || null
+    },
+    baseline: {
+      id: baseline.id || null,
+      build_id: baseline.build_id || null,
+      url: baseline.url || baseline.original_url || null
+    },
+    diff: buildCompactDiff(comparison, includeDiffs)
+  };
+}
+function summarizeComparisons(comparisons = []) {
+  return {
+    total: comparisons.length,
+    changed: comparisons.filter(isChangedComparison).length,
+    new: comparisons.filter(isNewComparison).length,
+    needs_review: comparisons.filter(comparison => comparison.needs_review).length
+  };
+}
+function buildAgentNextActions(context = {}, comparisonSummary = {}) {
+  if (context.status?.needs_review) {
+    return ['Inspect the changed and new comparisons before editing related UI.', 'Use approved baselines as the expected visual behavior.', 'Leave approval decisions to human reviewers.'];
+  }
+  if (comparisonSummary.total > 0) {
+    return ['Use the approved baseline and reviewed screenshots as current visual truth.', 'Prefer targeted edits that preserve identical comparisons.'];
+  }
+  return ['No comparisons were returned for this build context.', 'Open the build URL for more detail if this is unexpected.'];
+}
+function formatAgentStatus(status = {}) {
+  return {
+    needs_review: Boolean(status.needs_review),
+    reasons: status.reasons || [],
+    pending_comparisons: status.pending_comparisons || 0,
+    unresolved_comments: status.unresolved_comments || 0
+  };
+}
+function formatAgentSummary(context = {}, comparisons = []) {
+  return {
+    comparisons: context.summary?.comparisons || summarizeComparisons(comparisons),
+    review: context.summary?.review || {},
+    comments: context.summary?.comments || {
+      build: getBuildCommentsCount(context),
+      screenshot: getScreenshotCommentsCount(context)
+    }
+  };
+}
+function buildAgentBuildPayload(context, {
+  source = null,
+  include = [],
+  evidenceLimit = 10
+} = {}) {
+  let comparisons = context.comparisons || [];
+  let includeSet = new Set(include);
+  let includeDiffs = includeSet.has('diffs');
+  let changed = comparisons.filter(isChangedComparison);
+  let fresh = comparisons.filter(isNewComparison);
+  let evidence = [...changed, ...fresh].slice(0, evidenceLimit).map(comparison => buildCompactComparison(comparison, {
+    includeDiffs
+  }));
+  let comparisonSummary = summarizeComparisons(comparisons);
+  let payload = {
+    resource: 'build_agent_context',
+    source: context.source || source || 'cloud',
+    scope: context.scope || null,
+    project: {
+      organization: context.scope?.organization?.slug || null,
+      slug: context.scope?.project?.slug || null,
+      name: context.scope?.project?.name || null,
+      visibility: context.scope?.project?.visibility || null
+    },
+    build: context.build || null,
+    baseline: {
+      selected: context.baseline?.selected || null,
+      selection_reason: context.baseline?.selection_reason || null
+    },
+    status: formatAgentStatus(context.status),
+    summary: formatAgentSummary(context, comparisons),
+    evidence,
+    links: context.links || {},
+    preview: context.preview || null,
+    next_actions: buildAgentNextActions(context, comparisonSummary)
+  };
+  if (includeSet.has('screenshots')) {
+    payload.screenshots = context.screenshots || [];
+  }
+  if (includeSet.has('comments')) {
+    payload.comments = context.comments || {};
+  }
+  return payload;
+}
+function getBuildCommentsCount(context = {}) {
+  if (Array.isArray(context.comments?.build)) {
+    return context.comments.build.length;
+  }
+  if (Array.isArray(context.review?.comments)) {
+    return context.review.comments.length;
+  }
+  return 0;
+}
+function getScreenshotCommentsCount(context = {}) {
+  if (Number.isInteger(context.comments?.screenshot_count)) {
+    return context.comments.screenshot_count;
+  }
+  return 0;
+}
+function getReviewAssignmentsCount(context = {}) {
+  if (Array.isArray(context.review?.assignments)) {
+    return context.review.assignments.length;
+  }
+  return 0;
+}
+function formatNeedsReview(status = {}) {
+  if (!status || status.needs_review == null) {
+    return null;
+  }
+  let pending = status.pending_comparisons || 0;
+  let unresolved = status.unresolved_comments || 0;
+  if (!status.needs_review) {
+    return 'no';
+  }
+  return `yes · ${pending} comparisons · ${unresolved} unresolved comments`;
+}
 function formatConfirmedRegionLabels(regions = []) {
   return regions.map(region => region.label).filter(Boolean).slice(0, 3).join(' · ');
 }
@@ -193,13 +413,17 @@ function printComparisonList(output, comparisons = [], {
   for (let comparison of comparisons.slice(0, limit)) {
     let displayState = getComparisonDisplayState(comparison);
     let statusTone = getStatusTone(colors, displayState);
-    let screenshotName = comparison.screenshot?.name || comparison.name || comparison.id;
-    let diffPercentage = comparison.diff_percentage == null ? null : `${comparison.diff_percentage}%`;
-    let fingerprint = comparison.analysis?.fingerprint_hash || null;
+    let screenshotName = getComparisonName(comparison);
+    let rawDiffPercentage = getComparisonDiffPercentage(comparison);
+    let diffPercentage = rawDiffPercentage == null ? null : `${rawDiffPercentage}%`;
+    let fingerprint = getComparisonFingerprint(comparison);
     let details = [];
     if (diffPercentage) {
       details.push(diffPercentage);
     }
+    if (comparison.needs_review) {
+      details.push('needs review');
+    }
     if (fingerprint) {
       details.push(`fp:${fingerprint}`);
     }
@@ -216,23 +440,94 @@ function displayBuildContext(output, context) {
   output.header('context', 'build');
   let colors = output.getColors();
   let buildTone = getStatusTone(colors, context.build.status);
+  let comparisons = context.comparisons || [];
+  let screenshots = context.screenshots || [];
+  let reviewSummary = context.summary?.review || {};
+  let commentsSummary = context.summary?.comments || {};
+  let needsReview = formatNeedsReview(context.status);
+  let baseline = context.baseline?.selected || null;
   output.print(`  ${colors.bold(context.build.name || context.build.id)} ${buildTone((context.build.status || 'unknown').toUpperCase())}`);
   output.print(`  ${colors.dim(`@${context.scope.organization.slug}/${context.scope.project.slug}`)}`);
   output.blank();
-  output.labelValue('Comparisons', String(context.comparisons.length));
-  output.labelValue('Review', `${context.summary.review.pending || 0} pending · ${context.summary.review.approved || 0} approved · ${context.summary.review.rejected || 0} rejected`);
-  output.labelValue('Memory', `${context.review.comments.length} build comments · ${context.review.assignments.length} assignments`);
+  output.labelValue('Comparisons', String(comparisons.length));
+  if (screenshots.length > 0) {
+    output.labelValue('Screenshots', String(screenshots.length));
+  }
+  if (baseline) {
+    output.labelValue('Baseline', `${baseline.name || baseline.id || 'selected'}${context.baseline.selection_reason ? ` · ${context.baseline.selection_reason}` : ''}`);
+  }
+  if (needsReview) {
+    output.labelValue('Needs Review', needsReview);
+  }
+  output.labelValue('Review', `${reviewSummary.pending || 0} pending · ${reviewSummary.approved || 0} approved · ${reviewSummary.rejected || 0} rejected`);
+  output.labelValue('Memory', `${commentsSummary.build ?? getBuildCommentsCount(context)} build comments · ${commentsSummary.screenshot ?? getScreenshotCommentsCount(context)} screenshot comments · ${getReviewAssignmentsCount(context)} assignments`);
   if (context.preview) {
-    output.labelValue('Preview', `${context.preview.status}${context.preview.preview_url ? ' · available' : ''}`);
+    let previewUrl = context.preview.preview_url || context.preview.url;
+    output.labelValue('Preview', `${context.preview.status || 'unknown'}${previewUrl ? ' · available' : ''}`);
   }
   if (context.links?.build_url) {
     output.labelValue('Build URL', context.links.build_url);
   }
-  if (context.comparisons.length > 0) {
+  if (comparisons.length > 0) {
     output.blank();
     output.print('  Comparisons');
-    printComparisonList(output, context.comparisons);
+    printComparisonList(output, comparisons);
+  }
+}
+function formatAgentBuildContext(context) {
+  let comparisons = context.comparisons || [];
+  let changed = comparisons.filter(isChangedComparison);
+  let fresh = comparisons.filter(isNewComparison);
+  let needsReview = comparisons.filter(comparison => comparison.needs_review);
+  let baseline = context.baseline?.selected;
+  let lines = [`# Vizzly Visual Context: ${context.build?.name || context.build?.id || 'Build'}`, '', `Project: ${context.scope?.organization?.slug || 'unknown'}/${context.scope?.project?.slug || 'unknown'}`, `Build: ${context.build?.id || 'unknown'} (${context.build?.status || 'unknown'})`];
+  if (baseline) {
+    lines.push(`Approved baseline: ${baseline.name || baseline.id || 'selected'} (${baseline.approval_status || 'unknown'})`);
+  }
+  if (context.status) {
+    lines.push(`Needs review: ${context.status.needs_review ? 'yes' : 'no'} (${context.status.pending_comparisons || 0} pending comparisons)`);
+  }
+  if (context.preview?.url || context.preview?.preview_url) {
+    lines.push(`Preview: ${context.preview.url || context.preview.preview_url}`);
+  }
+  if (context.links?.build_url) {
+    lines.push(`Build URL: ${context.links.build_url}`);
+  }
+  if (context.links?.report_url) {
+    lines.push(`Report: ${context.links.report_url}`);
+  }
+  lines.push('');
+  lines.push('## Diff Summary');
+  lines.push(`- Total comparisons: ${comparisons.length}`);
+  lines.push(`- Changed: ${changed.length}`);
+  lines.push(`- New: ${fresh.length}`);
+  lines.push(`- Needs review: ${needsReview.length}`);
+  if (changed.length > 0 || fresh.length > 0) {
+    lines.push('');
+    lines.push('## Evidence To Inspect');
+    for (let comparison of [...changed, ...fresh].slice(0, 10)) {
+      let diffPercentage = getComparisonDiffPercentage(comparison);
+      let detail = diffPercentage == null ? '' : ` · ${diffPercentage}% diff`;
+      let diffUrl = comparison.diff?.image_url || comparison.analysis?.diff_image_url;
+      lines.push(`- ${getComparisonName(comparison)}: ${getComparisonDisplayState(comparison)}${detail}`);
+      if (diffUrl) {
+        lines.push(`  Diff: ${diffUrl}`);
+      }
+    }
+  }
+  if (comparisons.length > 0 && changed.length === 0 && fresh.length === 0) {
+    lines.push('');
+    lines.push('## Reviewed Screenshots');
+    for (let comparison of comparisons.slice(0, 10)) {
+      lines.push(`- ${getComparisonName(comparison)}: ${getComparisonDisplayState(comparison)}`);
+    }
+    if (comparisons.length > 10) {
+      lines.push(`- ...${comparisons.length - 10} more`);
+    }
   }
+  lines.push('');
+  lines.push('Use this as reviewed UI context. Treat approved baselines as visual truth, inspect meaningful diffs, and leave approval decisions to humans.');
+  return lines.join('\n');
 }
 function countScreenshotCommentEntries(groups = []) {
   return groups.reduce((total, group) => total + (group.comments?.length || 0), 0);
@@ -335,14 +630,28 @@ export async function contextBuildCommand(buildId, options = {}, globalOptions =
     if (!runtime) {
       return;
     }
+    let resolvedBuildId = resolveBuildContextId(buildId, runtime, deps);
     output.startSpinner('Fetching build context...');
-    let context = await runtime.provider.getBuildContext(buildId);
+    let context = await runtime.provider.getBuildContext(resolvedBuildId);
     output.stopSpinner();
+    if (globalOptions.json && options.agent && !options.full) {
+      output.data(buildAgentBuildPayload(context, {
+        source: runtime.source,
+        include: parseIncludeOption(options.include)
+      }));
+      output.cleanup();
+      return;
+    }
     if (globalOptions.json) {
       output.data(context);
       output.cleanup();
       return;
     }
+    if (options.agent) {
+      output.print(formatAgentBuildContext(context));
+      output.cleanup();
+      return;
+    }
     displayBuildContext(output, context);
     output.cleanup();
   } catch (error) {
@@ -513,7 +822,9 @@ export async function contextReviewQueueCommand(options = {}, globalOptions = {}
   }
 }
 export function validateContextBuildOptions(_options = {}) {
-  return validateSourceOption(_options.source);
+  let errors = validateSourceOption(_options.source);
+  errors.push(...validateIncludeOption(_options.include));
+  return errors;
 }
 export function validateContextComparisonOptions(options = {}) {
   let errors = [];