@vizzly-testing/cli 0.33.0 → 0.35.0

package/README.md

@@ -28,6 +28,16 @@ pnpm install -g @vizzly-testing/cli
 vizzly init
 ```
 
+For agent-friendly repos, install the Vizzly skill and add a short project
+`AGENTS.md` note:
+
+```bash
+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
@@ -47,9 +57,14 @@ 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.
 
@@ -104,12 +119,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.
 
@@ -129,9 +155,26 @@ 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.
+
+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:
+
+```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:
@@ -140,6 +183,13 @@ Generate a config file:
 vizzly init
 ```
 
+To teach project agents about Vizzly screenshot memory and the local visual TDD
+loop, add the repo-local skill and AGENTS.md guidance:
+
+```bash
+vizzly init --agent-guidance
+```
+
 Or create `vizzly.config.js` manually:
 
 ```javascript

package/dist/api/core.js

@@ -172,7 +172,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/cli.js

@@ -207,6 +207,7 @@ const formatHelp = (cmd, helper) => {
 };
 function extractGlobalOptionsFromArgv(argv, commandNames = null) {
   let configPath = null;
+  let tokenArg = null;
   let verboseMode = false;
   let logLevelArg = null;
   let jsonArg = null;
@@ -214,6 +215,11 @@ function extractGlobalOptionsFromArgv(argv, commandNames = null) {
     if ((argv[i] === '-c' || argv[i] === '--config') && argv[i + 1]) {
       configPath = argv[i + 1];
     }
+    if (argv[i] === '--token' && argv[i + 1]) {
+      tokenArg = argv[i + 1];
+    } else if (argv[i].startsWith('--token=')) {
+      tokenArg = argv[i].substring('--token='.length);
+    }
     if (argv[i] === '-v' || argv[i] === '--verbose') {
       verboseMode = true;
     }
@@ -234,6 +240,7 @@ function extractGlobalOptionsFromArgv(argv, commandNames = null) {
   }
   return {
     configPath,
+    tokenArg,
     verboseMode,
     logLevelArg,
     jsonArg
@@ -260,6 +267,7 @@ program.name('vizzly').description('Vizzly CLI for visual regression testing').v
 // We need to manually parse to get the config option early
 let {
   configPath,
+  tokenArg,
   verboseMode,
   logLevelArg,
   jsonArg
@@ -280,9 +288,11 @@ output.configure({
   color: colorOverride,
   json: jsonArg
 });
-const config = await loadConfig(configPath, {});
-const services = createServices(config);
-const pluginServices = createPluginServices(services);
+let config = await loadConfig(configPath, {
+  token: tokenArg
+});
+let services = createServices(config);
+let pluginServices = createPluginServices(services);
 let plugins = [];
 try {
   plugins = await loadPlugins(configPath, config);
@@ -303,16 +313,16 @@ try {
 } catch (error) {
   output.debug(`Plugin loading failed: ${error.message}`);
 }
-program.command('init').description('Initialize Vizzly in your project').option('--force', 'Overwrite existing configuration').action(async options => {
-  const globalOptions = program.opts();
+program.command('init').description('Initialize Vizzly in your project').option('--force', 'Overwrite existing configuration').option('--agent-skill', 'Install the repo-local Vizzly agent skill').option('--agent-guidance', 'Add Vizzly guidance to this project AGENTS.md and install the agent skill').option('--skip-agent-skill', 'Skip the Vizzly agent skill prompt').action(async options => {
+  let globalOptions = program.opts();
   await init({
     ...globalOptions,
     ...options,
     plugins
   });
 });
-program.command('upload').description('Upload screenshots to Vizzly').argument('<path>', 'Path to screenshots directory or file').option('-b, --build-name <name>', 'Build name for grouping').option('-m, --metadata <json>', 'Additional metadata as JSON').option('--batch-size <n>', 'Upload batch size', Number).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', Number).option('--branch <branch>', 'Git branch').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (path, options) => {
-  const globalOptions = program.opts();
+program.command('upload').description('Upload screenshots to Vizzly').argument('<path>', 'Path to screenshots directory').option('-b, --build-name <name>', 'Build name for grouping').option('-m, --metadata <json>', 'Additional metadata as JSON').option('--batch-size <n>', 'Upload batch size', Number).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', Number).option('--branch <branch>', 'Git branch').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (path, options) => {
+  let globalOptions = program.opts();
 
   // Validate options
   const validationErrors = validateUploadOptions(path, options);
@@ -323,7 +333,10 @@ program.command('upload').description('Upload screenshots to Vizzly').argument('
     }
     process.exit(1);
   }
-  await uploadCommand(path, options, globalOptions);
+  let result = await uploadCommand(path, options, globalOptions);
+  if (result?.exitCode) {
+    process.exit(result.exitCode);
+  }
 });
 
 // TDD command with subcommands - local visual review with an interactive dashboard

package/dist/client/index.js

@@ -8,22 +8,27 @@ import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { dirname, join, parse } from 'node:path';
 import { getBuildId, getServerUrl, isTddMode, setVizzlyEnabled } from '../utils/environment-config.js';
-import { createScreenshotProperties } from '../utils/screenshot-options.js';
+import { normalizeScreenshotOptions } from '../utils/screenshot-options.js';
 
 // Internal client state
 let currentClient = null;
+let currentServerUrl = null;
 let isDisabled = false;
+let currentFailOnDiff = false;
 
 // Default timeout for screenshot requests (30 seconds)
 let DEFAULT_TIMEOUT_MS = 30000;
 
 // Log levels for client SDK output control
-export let LOG_LEVELS = {
+export let LOG_LEVELS = Object.freeze({
   debug: 0,
   info: 1,
   warn: 2,
   error: 3
-};
+});
+function getEnvFailOnDiff(env = process.env) {
+  return env.VIZZLY_FAIL_ON_DIFF === 'true' || env.VIZZLY_FAIL_ON_DIFF === '1';
+}
 
 /**
  * Check if client should log at the given level
@@ -56,6 +61,7 @@ function isVizzlyDisabled() {
 function disableVizzly() {
   isDisabled = true;
   currentClient = null;
+  currentServerUrl = null;
 }
 
 /**
@@ -67,7 +73,8 @@ function disableVizzly() {
 export function autoDiscoverTddServer(startDir, deps = {}) {
   let {
     exists = existsSync,
-    readFile = readFileSync
+    readFile = readFileSync,
+    env = process.env
   } = deps;
   try {
     // Look for .vizzly/server.json in current directory and parent directories
@@ -80,6 +87,7 @@ export function autoDiscoverTddServer(startDir, deps = {}) {
           let serverInfo = JSON.parse(readFile(serverJsonPath, 'utf8'));
           if (serverInfo.port) {
             let url = `http://localhost:${serverInfo.port}`;
+            currentFailOnDiff = getEnvFailOnDiff(env) || Boolean(serverInfo.failOnDiff);
             return url;
           }
         } catch {
@@ -104,6 +112,7 @@ function getClient() {
   }
   if (!currentClient) {
     let serverUrl = getServerUrl();
+    currentFailOnDiff = getEnvFailOnDiff();
 
     // Auto-detect local TDD server and enable Vizzly if TDD server is found
     if (!serverUrl) {
@@ -116,7 +125,10 @@ function getClient() {
 
     // If we have a server URL, create the client (regardless of initial enabled state)
     if (serverUrl) {
-      currentClient = createSimpleClient(serverUrl);
+      currentServerUrl = serverUrl;
+      currentClient = createSimpleClient(serverUrl, {
+        failOnDiff: currentFailOnDiff
+      });
     }
   }
   return currentClient;
@@ -183,28 +195,38 @@ function httpPost(url, body, timeoutMs) {
  * Create a simple HTTP client for screenshots
  * @private
  */
-function createSimpleClient(serverUrl) {
+function createSimpleClient(serverUrl, clientOptions = {}) {
+  let {
+    failOnDiff = false
+  } = clientOptions;
   return {
     async screenshot(name, imageBuffer, options = {}) {
+      let normalizedOptions = normalizeScreenshotOptions(options);
+      let requestTimeout = normalizedOptions.requestTimeout || DEFAULT_TIMEOUT_MS;
+      for (let warning of normalizedOptions.warnings) {
+        console.warn(`[vizzly] ${warning.message}`);
+      }
       try {
         // If it's a string, assume it's a file path and send directly
         // Otherwise it's a Buffer, so convert to base64
         let isFilePath = typeof imageBuffer === 'string';
         let image = isFilePath ? imageBuffer : imageBuffer.toString('base64');
         let type = isFilePath ? 'file-path' : 'base64';
-        let requestTimeout = options.requestTimeout || DEFAULT_TIMEOUT_MS;
-        let properties = createScreenshotProperties(options);
+        let screenshotData = {
+          buildId: normalizedOptions.buildId ?? getBuildId(),
+          name,
+          image,
+          type,
+          properties: normalizedOptions.properties
+        };
+        if (normalizedOptions.warnings.length > 0) {
+          screenshotData.warnings = normalizedOptions.warnings;
+        }
         let httpStart = Date.now();
         let {
           status,
           json
-        } = await httpPost(`${serverUrl}/screenshot`, {
-          buildId: getBuildId(),
-          name,
-          image,
-          type,
-          properties
-        }, requestTimeout);
+        } = await httpPost(`${serverUrl}/screenshot`, screenshotData, requestTimeout);
         let httpMs = Date.now() - httpStart;
         if (shouldLogClient('debug')) {
           console.debug(`[vizzly-client] ${name} HTTP completed in ${httpMs}ms`);
@@ -215,6 +237,9 @@ function createSimpleClient(serverUrl) {
           // The summary will show all failures at the end
           if (status === 422 && json.tddMode && json.comparison) {
             let comp = json.comparison;
+            if (failOnDiff) {
+              throw new Error(`Visual diff detected for "${comp.name}" (${comp.diffPercentage ?? 0}% difference)`);
+            }
 
             // Return success so test continues and captures remaining screenshots
             // Visual diff details will be shown in the summary after tests complete
@@ -227,12 +252,15 @@ function createSimpleClient(serverUrl) {
           }
           throw new Error(`Screenshot failed: ${status} - ${json.error || 'Unknown error'}`);
         }
+        if (failOnDiff && json?.tddMode && ['diff', 'failed'].includes(json.status)) {
+          throw new Error(`Visual diff detected for "${json.name || name}" (${json.diffPercentage ?? 0}% difference)`);
+        }
         return json;
       } catch (error) {
         // Handle timeout
         if (error.message === 'Request timeout') {
           if (shouldLogClient('error')) {
-            console.error(`[vizzly] Screenshot timed out for "${name}" after ${DEFAULT_TIMEOUT_MS / 1000}s`);
+            console.error(`[vizzly] Screenshot timed out for "${name}" after ${requestTimeout / 1000}s`);
           }
           disableVizzly();
           return null;
@@ -308,7 +336,7 @@ function createSimpleClient(serverUrl) {
  * await vizzlyScreenshot('checkout-form', screenshot, {
  *   properties: {
  *     browser: 'chrome',
- *     viewport: '1920x1080'
+ *     viewport: { width: 1920, height: 1080 }
  *   },
  *   threshold: 5
  * });
@@ -366,8 +394,20 @@ export function isVizzlyReady() {
  * @param {boolean} [config.enabled] - Enable/disable screenshots
  */
 export function configure(config = {}) {
+  if ('failOnDiff' in config) {
+    currentFailOnDiff = config.failOnDiff === true;
+  } else if ('serverUrl' in config) {
+    currentFailOnDiff = getEnvFailOnDiff();
+  }
   if ('serverUrl' in config) {
-    currentClient = config.serverUrl ? createSimpleClient(config.serverUrl) : null;
+    currentServerUrl = config.serverUrl || null;
+    currentClient = config.serverUrl ? createSimpleClient(config.serverUrl, {
+      failOnDiff: currentFailOnDiff
+    }) : null;
+  } else if ('failOnDiff' in config && currentClient && currentServerUrl) {
+    currentClient = createSimpleClient(currentServerUrl, {
+      failOnDiff: currentFailOnDiff
+    });
   }
   if (typeof config.enabled === 'boolean') {
     setVizzlyEnabled(config.enabled);
@@ -397,10 +437,11 @@ export function getVizzlyInfo() {
   let client = getClient();
   return {
     enabled: !isVizzlyDisabled(),
-    serverUrl: getServerUrl(),
+    serverUrl: currentServerUrl || getServerUrl() || null,
     ready: !isVizzlyDisabled() && client !== null,
-    buildId: getBuildId(),
+    buildId: getBuildId() || null,
     tddMode: isTddMode(),
-    disabled: isVizzlyDisabled()
+    disabled: isVizzlyDisabled(),
+    failOnDiff: currentFailOnDiff
   };
 }

package/dist/commands/api.js

@@ -65,7 +65,8 @@ export function appendApiQuery(endpoint, queryOption) {
 }
 export function validateApiRequest({
   endpoint,
-  method
+  method,
+  hasData = false
 }) {
   let errors = [];
   if (method !== 'GET' && method !== 'POST') {
@@ -75,6 +76,9 @@ export function validateApiRequest({
   if (method === 'POST' && !isAllowedPostEndpoint(endpoint)) {
     errors.push(`POST not allowed for ${endpoint}. Only approve, reject, and comment endpoints support POST.`);
   }
+  if (hasData && method !== 'POST') {
+    errors.push('Request data requires --method POST.');
+  }
   return errors;
 }
 export function buildApiRequest({
@@ -85,7 +89,8 @@ export function buildApiRequest({
   let method = normalizeApiMethod(options.method || 'GET');
   let errors = validateApiRequest({
     endpoint: normalizedEndpoint,
-    method
+    method,
+    hasData: options.data !== undefined
   });
   if (errors.length > 0) {
     return {
@@ -239,7 +244,8 @@ export function validateApiOptions(endpoint, options = {}) {
   let method = normalizeApiMethod(options.method || 'GET');
   errors.push(...validateApiRequest({
     endpoint: normalizedEndpoint,
-    method
+    method,
+    hasData: options.data !== undefined
   }));
   return errors;
 }