@vizzly-testing/cli 0.29.6 → 0.31.0

package/README.md

@@ -1,23 +1,23 @@
 # Vizzly CLI
 
-> Visual proof that your UI works
+> Visual review for agents and teams
 
 [![npm version](https://img.shields.io/npm/v/@vizzly-testing/cli.svg)](https://www.npmjs.com/package/@vizzly-testing/cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Visual bugs slip through code review. They hide in pixel-perfect mockups, sneak past unit tests, and show up right when you're about to ship. Vizzly catches them first.
+Vizzly keeps the visual truth behind your UI: approved baselines, meaningful diffs, review state, comments, and preview links in one place. That makes it useful for humans reviewing product changes and for LLM agents that need to understand what the UI is supposed to look like before they edit it.
 
-Unlike tools that re-render components in isolation, Vizzly captures screenshots directly from your functional tests—the *real thing*. Whether you're validating AI-generated code or testing manual changes, you get visual proof before anything hits production.
+Unlike tools that re-render components in isolation, Vizzly captures screenshots directly from your functional tests: the real thing. Whether you're validating AI-generated code or testing manual changes, you get reviewed visual evidence before anything hits production.
 
 ## Why Vizzly?
 
-**Local TDD workflow.** See changes as you type, not after CI. The `vizzly tdd` command runs a local dashboard that compares screenshots instantly—no cloud roundtrip, no waiting.
+**Local TDD workflow.** See changes as you type, not after CI. The `vizzly tdd` command runs a local dashboard that compares screenshots instantly and exposes the current workspace as local context.
 
-**Smart diffing with Honeydiff.** Our Rust-based comparison engine is 12x faster than alternatives and ignores the noise: timestamps, ads, font rendering differences. It finds real changes.
+**Meaningful diff metadata.** Vizzly stores rich diff evidence: changed regions, cluster metadata, fingerprints, hotspots, confirmed regions, and image URLs. Agents can inspect what changed instead of guessing from a pass/fail label.
 
 **Any screenshot source.** Playwright, Cypress, Puppeteer, Selenium, native mobile apps, or even design mockups. If you can capture it, Vizzly can compare it.
 
-**Team-based pricing.** Pay for your team, not your screenshots. Test everything without budget anxiety.
+**Approved baselines as truth.** Cloud context carries human review state. Local context carries the downloaded or generated baseline metadata. That is the bridge between TDD locally and collaborative review in Vizzly.
 
 ## Quick Start
 
@@ -58,6 +58,33 @@ export VIZZLY_TOKEN=your-project-token
 vizzly run "npm test" --wait
 ```
 
+### Visual Context For Agents
+
+Use `vizzly context` when you want Vizzly to act like a visual context store, not just a test runner.
+
+This is especially useful for LLM agents, automation, and quick debugging loops. Instead of
+making a bunch of narrow API calls, you can ask for one build, comparison, screenshot, or review
+queue bundle and get the evidence in one place.
+
+```bash
+# Cloud context for a build or comparison
+vizzly context build abc123
+vizzly context comparison def456 --json
+
+# Local workspace context from .vizzly/
+vizzly context build current --source local
+vizzly context build current --source local --agent
+vizzly context screenshot build-detail-screenshots --source local --json
+```
+
+`--json` is the durable automation path. `--agent` gives a compact handoff for prompt assembly and local dogfooding. Add `--full` when an agent really needs the complete build context payload, or `--include screenshots,diffs,comments` when the compact JSON needs selected detail.
+
+Local context is read-only and file-backed. It reads your existing `.vizzly` workspace state from
+TDD runs, including screenshots, diffs, and any saved hotspot or region metadata.
+
+Cloud context is also read-only right now. That is intentional. It keeps the trust model simple:
+Vizzly helps you see and inspect visual changes, while people still decide what gets approved.
+
 ## Capture Screenshots
 
 Add screenshots to your existing tests:
@@ -116,6 +143,7 @@ export default {
 | `vizzly tdd start` | Start local TDD server with dashboard |
 | `vizzly tdd run "cmd"` | Run tests once, generate static report |
 | `vizzly run "cmd"` | Run tests with cloud integration |
+| `vizzly context ...` | Fetch visual context bundles for builds, comparisons, and screenshots |
 | `vizzly upload <dir>` | Upload existing screenshots |
 | `vizzly login` | Authenticate via browser |
 | `vizzly doctor` | Validate local setup |

package/dist/api/client.js

@@ -14,6 +14,9 @@ import { buildApiUrl, buildRequestHeaders, buildUserAgent, extractErrorBody, isA
  * Default API URL
  */
 export const DEFAULT_API_URL = 'https://app.vizzly.dev';
+function isProjectToken(token) {
+  return typeof token === 'string' && token.startsWith('vzt_');
+}
 
 /**
  * Create an API client with the given configuration
@@ -63,7 +66,7 @@ export function createApiClient(options = {}) {
       let errorBody = await extractErrorBody(response);
 
       // Handle 401 with token refresh
-      if (shouldRetryWithRefresh(response.status, isRetry, await hasRefreshToken())) {
+      if (shouldRetryWithRefresh(response.status, isRetry, !isProjectToken(token) && (await hasRefreshToken()))) {
         let refreshed = await attemptTokenRefresh();
         if (refreshed) {
           token = refreshed;
@@ -73,7 +76,7 @@ export function createApiClient(options = {}) {
 
       // Auth error
       if (isAuthError(response.status)) {
-        throw new AuthError('Invalid or expired API token. Link a project via "vizzly project:select" or set VIZZLY_TOKEN.');
+        throw new AuthError('Invalid or expired API token. Run "vizzly project link <org>/<project>" or set VIZZLY_TOKEN.');
       }
 
       // Other errors
@@ -119,7 +122,7 @@ export function createApiClient(options = {}) {
       await saveAuthTokens({
         accessToken: data.accessToken,
         refreshToken: data.refreshToken,
-        expiresAt: data.expiresAt,
+        expiresAt: data.expiresAt || new Date(Date.now() + data.expiresIn * 1000).toISOString(),
         user: auth.user
       });
       return data.accessToken;

package/dist/api/endpoints.js

@@ -210,6 +210,65 @@ export async function getComparison(client, comparisonId) {
   return response.comparison;
 }
 
+/**
+ * Get build context bundle for agent and reviewer workflows
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @returns {Promise<Object>} Build context bundle
+ */
+export async function getBuildContext(client, buildId) {
+  return client.request(`/api/sdk/context/builds/${buildId}`);
+}
+
+/**
+ * Get comparison context bundle with similarity and history
+ * @param {Object} client - API client
+ * @param {string} comparisonId - Comparison ID
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Comparison context bundle
+ */
+export async function getComparisonContext(client, comparisonId, options = {}) {
+  let endpoint = buildEndpointWithParams(`/api/sdk/context/comparisons/${comparisonId}`, options);
+  return client.request(endpoint);
+}
+
+/**
+ * Get screenshot context bundle for a screenshot name
+ * @param {Object} client - API client
+ * @param {string} screenshotName - Screenshot name
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Screenshot context bundle
+ */
+export async function getScreenshotContext(client, screenshotName, options = {}) {
+  let encodedName = encodeURIComponent(screenshotName);
+  let endpoint = buildEndpointWithParams(`/api/sdk/context/screenshots/${encodedName}`, options);
+  return client.request(endpoint);
+}
+
+/**
+ * Get project-scoped similar comparisons for a fingerprint hash
+ * @param {Object} client - API client
+ * @param {string} fingerprintHash - Honeydiff fingerprint hash
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Fingerprint context bundle
+ */
+export async function getSimilarFingerprintContext(client, fingerprintHash, options = {}) {
+  let encodedFingerprint = encodeURIComponent(fingerprintHash);
+  let endpoint = buildEndpointWithParams(`/api/sdk/context/fingerprints/${encodedFingerprint}/similar`, options);
+  return client.request(endpoint);
+}
+
+/**
+ * Get pending review queue context for a project
+ * @param {Object} client - API client
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Review queue context bundle
+ */
+export async function getReviewQueueContext(client, options = {}) {
+  let endpoint = buildEndpointWithParams('/api/sdk/context/review-queue', options);
+  return client.request(endpoint);
+}
+
 /**
  * Search for comparisons by name
  * @param {Object} client - API client

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, buildShaCheckPayload, buildUserAgent, computeSha256, extractErrorBody, findScreenshotBySha, isAuthError, isRateLimited, parseApiError, partitionByShaExistence, shaExists, shouldRetryWithRefresh } from './core.js';
 
 // Endpoint functions
-export { checkShas, createBuild, finalizeBuild, finalizeParallelBuild, getBatchHotspots, getBuild, getBuilds, getComparison, getPreviewInfo, getScreenshotHotspots, getTddBaselines, getTokenContext, searchComparisons, updateBuildStatus, uploadPreviewZip, uploadScreenshot } from './endpoints.js';
+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';

package/dist/auth/core.js

@@ -162,7 +162,7 @@ export function buildTokenData(response, existingUser = null) {
  * @returns {{ valid: boolean, error: Error|null }}
  */
 export function validateTokens(auth, requiredField = 'accessToken') {
-  if (!auth || !auth[requiredField]) {
+  if (!auth?.[requiredField]) {
     let message = requiredField === 'refreshToken' ? 'No refresh token found. Please run "vizzly login" first.' : 'No authentication token found. Please run "vizzly login" first.';
     return {
       valid: false,

package/dist/auth/index.js

@@ -9,13 +9,14 @@
 
 // Re-export token store utilities for convenience
 import { clearAuthTokens, getAuthTokens, saveAuthTokens } from '../utils/global-config.js';
-export { clearAuthTokens, getAuthTokens, saveAuthTokens };
+
 // HTTP client factory
 export { createAuthClient } from './client.js';
 // Core pure functions
 export { buildAuthHeader, buildAuthUserAgent, buildDevicePollPayload, buildLogoutPayload, buildRefreshPayload, buildRequestHeaders, buildTokenData, parseAuthError, parseAuthenticatedError, validateTokens } from './core.js';
 // Auth operations (take dependencies as parameters)
 export { completeDeviceFlow, initiateDeviceFlow, isAuthenticated, logout, pollDeviceAuthorization, refresh, whoami } from './operations.js';
+export { clearAuthTokens, getAuthTokens, saveAuthTokens };
 
 /**
  * Create a token store adapter from global-config functions