@vizzly-testing/cli 0.35.0 → 0.35.1

package/README.md

@@ -40,17 +40,31 @@ Use `vizzly init --agent-skill` to install only the local skill, or
 
 ### Start Local TDD
 
-Start the TDD server, run your tests, and open the dashboard at
-`http://localhost:47392`.
+Start the TDD server, run your tests, and open the dashboard at the URL the
+command prints. Add `--open` when you want Vizzly to open the dashboard for
+you. If the default port is busy, Vizzly picks the next available port; use the
+printed `--port` value with `vizzly tdd status` or `vizzly tdd stop`.
 
 ```bash
-vizzly tdd start
+vizzly tdd start --open
 pnpm test -- --watch
 ```
 
 The dashboard shows screenshots, baselines, and diffs as they arrive. Accept or
 reject changes right from the UI.
 
+For a one-off local check, wrap the test command with `tdd run`:
+
+```bash
+vizzly tdd run "pnpm test" --no-open
+vizzly context build current --source local --agent
+```
+
+That run writes review data under `.vizzly/` and prints a context command you
+can use for follow-up inspection. If screenshots were captured, Vizzly also
+generates `.vizzly/report/index.html`; omit `--no-open` when you want that
+report opened automatically.
+
 ### Run With Cloud Review
 
 Use cloud builds when you want shared baselines, team review, and CI status:
@@ -162,9 +176,11 @@ vizzly upload ./screenshots --threshold 2 --min-cluster-size 4 --batch-size 10 -
 `--upload-timeout` controls the upload client's timeout, including how long
 `--wait` polls for build processing.
 
-CI workflows can force every screenshot through even when the SHA cache says it
-already uploaded. Parallel jobs should use the same stable ID, then finalize
-that ID after every shard completes:
+When `vizzly run` sends screenshots to Vizzly, the CLI first asks the API to
+resolve each screenshot by SHA. If Vizzly already has the image bytes, the CLI
+creates the screenshot record without re-uploading the image. CI workflows can
+force every screenshot through with `--upload-all`. Parallel jobs should use the
+same stable ID, then finalize that ID after every shard completes:
 
 ```bash
 vizzly run "pnpm test" --upload-all --parallel-id "$GITHUB_RUN_ID"
@@ -206,10 +222,18 @@ export default {
 | Command | What it does |
 | --- | --- |
 | `vizzly tdd start` | Start the local TDD server and dashboard. |
-| `vizzly tdd run "cmd"` | Run tests once and generate a static visual report. |
+| `vizzly tdd status` | Check the local TDD server for this project. |
+| `vizzly tdd list` | List running local TDD servers. |
+| `vizzly tdd stop` | Stop the local TDD server for this project. |
+| `vizzly tdd run "cmd"` | Run tests once and write local review data under `.vizzly/`. |
 | `vizzly run "cmd"` | Run tests with cloud build and review integration. |
 | `vizzly context ...` | Fetch visual context for builds, comparisons, screenshots, and review queues. |
 | `vizzly upload <dir>` | Upload an existing folder of screenshots. |
+| `vizzly preview <dir>` | Upload static build output for in-context review. |
+| `vizzly approve <comparison-id>` | Approve a visual comparison. |
+| `vizzly reject <comparison-id>` | Reject a visual comparison with a reason. |
+| `vizzly comment <build-id>` | Add a build comment. |
+| `vizzly config [key]` | Inspect resolved configuration values. |
 | `vizzly login` | Authenticate through the browser. |
 | `vizzly doctor` | Validate your local setup. |
 

package/dist/api/core.js

@@ -70,9 +70,9 @@ export function buildRequestHeaders({
 // ============================================================================
 
 /**
- * Build payload for screenshot upload
+ * Build payload for screenshot upload or SHA resolution
  * @param {string} name - Screenshot name
- * @param {Buffer} buffer - Image data
+ * @param {Buffer|null} buffer - Image data, or null when resolving by SHA
  * @param {Object} metadata - Screenshot metadata (viewport, browser, etc.)
  * @param {string|null} sha256 - Pre-computed SHA256 hash (optional)
  * @returns {Object} Screenshot upload payload
@@ -80,15 +80,28 @@ export function buildRequestHeaders({
 export function buildScreenshotPayload(name, buffer, metadata = {}, sha256 = null) {
   let payload = {
     name,
-    image_data: buffer.toString('base64'),
     properties: metadata ?? {}
   };
+  if (buffer) {
+    payload.image_data = buffer.toString('base64');
+  }
   if (sha256) {
     payload.sha256 = sha256;
   }
   return payload;
 }
 
+/**
+ * Build payload for server-side screenshot resolution without sending image bytes
+ * @param {string} name - Screenshot name
+ * @param {Object} metadata - Screenshot metadata (viewport, browser, etc.)
+ * @param {string} sha256 - Pre-computed SHA256 hash
+ * @returns {Object} Screenshot resolution payload
+ */
+export function buildScreenshotResolvePayload(name, metadata = {}, sha256) {
+  return buildScreenshotPayload(name, null, metadata, sha256);
+}
+
 /**
  * Build payload for build creation
  * @param {Object} options - Build options

package/dist/api/endpoints.js

@@ -7,7 +7,7 @@
 
 import { VizzlyError } from '../errors/vizzly-error.js';
 import * as output from '../utils/output.js';
-import { buildBuildPayload, buildEndpointWithParams, buildQueryParams, buildScreenshotCheckObject, buildScreenshotPayload, buildShaCheckPayload, computeSha256, findScreenshotBySha, shaExists } from './core.js';
+import { buildBuildPayload, buildEndpointWithParams, buildQueryParams, buildScreenshotPayload, buildScreenshotResolvePayload, buildShaCheckPayload, computeSha256 } from './core.js';
 
 // ============================================================================
 // Build Endpoints
@@ -144,6 +144,16 @@ export async function checkShas(client, screenshots, buildId) {
     };
   }
 }
+function canUploadBytesAfterShaResolveError(error) {
+  let status = error?.context?.status;
+
+  // Network failures, older servers, and server errors should degrade to the
+  // slower byte upload path. Auth and ownership errors must still surface.
+  if (!status) return true;
+  if (status >= 500) return true;
+  if (status === 400 && error.message?.includes('image_data')) return true;
+  return false;
+}
 
 /**
  * Upload a screenshot with SHA deduplication
@@ -168,23 +178,36 @@ export async function uploadScreenshot(client, buildId, name, buffer, metadata =
     });
   }
 
-  // Normal flow with SHA deduplication
+  // Normal flow with server-side SHA resolution.
   let sha256 = computeSha256(buffer);
-  let checkObj = buildScreenshotCheckObject(sha256, name, metadata);
-  let checkResult = await checkShas(client, [checkObj], buildId);
-  if (shaExists(checkResult, sha256)) {
-    // File already exists, screenshot record was automatically created
-    let screenshot = findScreenshotBySha(checkResult, sha256);
-    return {
-      message: 'Screenshot already exists, skipped upload',
-      sha256,
-      skipped: true,
-      screenshot,
-      fromExisting: true
-    };
+  let resolvePayload = buildScreenshotResolvePayload(name, metadata, sha256);
+  try {
+    let resolveResult = await client.request(`/api/sdk/builds/${buildId}/screenshots`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(resolvePayload)
+    });
+    if (resolveResult?.upload_required === false) {
+      return {
+        message: 'Screenshot already exists, skipped upload',
+        sha256,
+        skipped: true,
+        screenshot: resolveResult,
+        fromExisting: true
+      };
+    }
+  } catch (error) {
+    if (!canUploadBytesAfterShaResolveError(error)) {
+      throw error;
+    }
+    output.debug('sha-resolve', 'failed, uploading screenshot bytes', {
+      error: error.message
+    });
   }
 
-  // File doesn't exist, proceed with upload
+  // File doesn't exist, or resolve failed; proceed with upload.
   let payload = buildScreenshotPayload(name, buffer, metadata, sha256);
   return client.request(`/api/sdk/builds/${buildId}/screenshots`, {
     method: 'POST',

package/dist/api/index.js

@@ -13,7 +13,7 @@
 // Client factory
 export { createApiClient, DEFAULT_API_URL } from './client.js';
 // Core pure functions
-export { buildApiUrl, buildAuthHeader, buildBuildPayload, buildEndpointWithParams, buildQueryParams, buildRequestHeaders, buildScreenshotCheckObject, buildScreenshotPayload, buildShaCheckPayload, buildUserAgent, computeSha256, extractErrorBody, findScreenshotBySha, isAuthError, isRateLimited, parseApiError, partitionByShaExistence, shaExists, shouldRetryWithRefresh } from './core.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';