@vizzly-testing/cli 0.34.0 → 0.35.1

package/README.md

@@ -35,28 +35,50 @@ For agent-friendly repos, install the Vizzly skill and add a short project
 vizzly init --agent-guidance
 ```
 
+Use `vizzly init --agent-skill` to install only the local skill, or
+`vizzly init --skip-agent-skill` when you want config without the agent prompt.
+
 ### 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:
 
 ```bash
 vizzly login
+vizzly project link your-org/your-project
 vizzly run "pnpm test" --wait
 ```
 
+`vizzly login` authenticates your user account. `vizzly project link` creates a
+project-scoped upload credential for this checkout, which `vizzly run` uses for
+cloud uploads.
+
 `--wait` blocks until Vizzly finishes processing the build. It exits with code
 `1` when visual differences need review.
 
@@ -111,12 +133,23 @@ test('homepage looks correct', async ({ page }) => {
 
   let screenshot = await page.screenshot();
   await vizzlyScreenshot('homepage', screenshot, {
-    browser: 'chrome',
-    viewport: '1920x1080'
+    fullPage: true,
+    requestTimeout: 5000,
+    properties: {
+      browser: 'chrome',
+      viewport: { width: 1920, height: 1080 },
+    },
   });
 });
 ```
 
+`properties` is your metadata bag for baseline grouping, filtering, and
+debugging. SDK options such as `threshold`, `minClusterSize`, `fullPage`,
+`requestTimeout`, and `buildId` stay at the top level. If one of those reserved
+SDK options is accidentally placed inside `properties`, Vizzly removes it from
+metadata, applies it as an option when possible, and warns so the call site can
+be cleaned up.
+
 The client SDK is lightweight. It posts screenshots to the local Vizzly server
 or the cloud build wrapper. It works with any test runner.
 
@@ -136,9 +169,28 @@ await vizzlyScreenshot('homepage', './screenshots/homepage.png');
 Or upload an existing folder of screenshots:
 
 ```bash
-vizzly upload ./screenshots
+vizzly upload ./screenshots --threshold 2 --min-cluster-size 4 --batch-size 10 --upload-timeout 60000
 ```
 
+`--batch-size` controls how many screenshots are uploaded per request.
+`--upload-timeout` controls the upload client's timeout, including how long
+`--wait` polls for build processing.
+
+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"
+vizzly finalize "$GITHUB_RUN_ID"
+```
+
+For smoke jobs where cloud credentials are intentionally unavailable, add
+`--allow-no-token` to `vizzly run` and Vizzly will keep the local screenshot
+server path working without creating a cloud build.
+
 ## Configuration
 
 Generate a config file:
@@ -170,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
@@ -172,7 +185,8 @@ export function buildScreenshotCheckObject(sha256, name, metadata = {}) {
     name,
     browser: meta.browser || 'chrome',
     viewport_width: meta.viewport?.width || meta.viewport_width || 1920,
-    viewport_height: meta.viewport?.height || meta.viewport_height || 1080
+    viewport_height: meta.viewport?.height || meta.viewport_height || 1080,
+    properties: meta
   };
 }
 

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';