@vizzly-testing/cli 0.33.0 → 0.35.0

package/dist/uploader/operations.js

@@ -386,23 +386,25 @@ export async function upload({
     let buildInfo = buildBuildInfo(uploadOptions, defaultBranch);
     let build = await createBuild(client, buildInfo);
     let buildId = build.id;
-
-    // Check existing files
-    let {
-      toUpload,
-      existing,
-      screenshots
-    } = await checkExistingFiles({
-      fileMetadata,
-      client,
-      signal,
-      buildId,
-      deps: {
-        checkShas,
-        createError,
-        output
-      }
-    });
+    let toUpload = fileMetadata;
+    let existing = [];
+    let screenshots = [];
+    if (!uploadOptions.uploadAll) {
+      let existingResult = await checkExistingFiles({
+        fileMetadata,
+        client,
+        signal,
+        buildId,
+        deps: {
+          checkShas,
+          createError,
+          output
+        }
+      });
+      toUpload = existingResult.toUpload;
+      existing = existingResult.existing;
+      screenshots = existingResult.screenshots;
+    }
     onProgress(buildDeduplicationProgress(toUpload.length, existing.length, files.length));
 
     // Upload files

package/dist/utils/config-loader.js

@@ -2,7 +2,7 @@ import { resolve } from 'node:path';
 import { cosmiconfigSync } from 'cosmiconfig';
 import { CONFIG_DEFAULTS, deepMerge } from '../config/core.js';
 import { validateVizzlyConfigWithDefaults } from './config-schema.js';
-import { getApiToken, getApiUrl, getBuildName, getParallelId } from './environment-config.js';
+import { getApiToken, getApiUrl, getBuildName, getMinClusterSize, getParallelId, getThreshold } from './environment-config.js';
 import { getAccessToken } from './global-config.js';
 import * as output from './output.js';
 import { getActiveProjectLink } from './project-link-store.js';
@@ -26,10 +26,12 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
   mergeConfig(config, validatedFileConfig);
 
   // 3. Override with environment variables (higher priority than fallbacks)
-  const envApiKey = getApiToken();
-  const envApiUrl = getApiUrl();
-  const envBuildName = getBuildName();
-  const envParallelId = getParallelId();
+  let envApiKey = getApiToken();
+  let envApiUrl = getApiUrl();
+  let envBuildName = getBuildName();
+  let envParallelId = getParallelId();
+  let envThreshold = getThreshold();
+  let envMinClusterSize = getMinClusterSize();
   if (envApiKey) {
     config.apiKey = envApiKey;
     output.debug('config', 'using token from environment');
@@ -40,6 +42,10 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
     output.debug('config', 'using build name from environment');
   }
   if (envParallelId) config.parallelId = envParallelId;
+  if (envThreshold !== undefined) config.comparison.threshold = envThreshold;
+  if (envMinClusterSize !== undefined) {
+    config.comparison.minClusterSize = envMinClusterSize;
+  }
 
   // 4. Apply CLI overrides (highest priority)
   if (cliOverrides.token) {
@@ -109,7 +115,7 @@ function applyCLIOverrides(config, cliOverrides = {}) {
   }
 
   // Comparison overrides
-  if (cliOverrides.threshold !== undefined) config.comparison.threshold = cliOverrides.threshold;
+  if (cliOverrides.threshold !== undefined) config.comparison.threshold = Number(cliOverrides.threshold);
   if (cliOverrides.minClusterSize !== undefined) {
     config.comparison.minClusterSize = Number(cliOverrides.minClusterSize);
   }

package/dist/utils/context.js

@@ -11,6 +11,37 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+function getGlobalConfigPath() {
+  return join(process.env.VIZZLY_HOME || join(homedir(), '.vizzly'), 'config.json');
+}
+function readJsonFile(path) {
+  try {
+    if (existsSync(path)) {
+      return JSON.parse(readFileSync(path, 'utf8'));
+    }
+  } catch {
+    // Optional context should never block the command that is rendering it.
+  }
+  return null;
+}
+function readGlobalConfig() {
+  return readJsonFile(getGlobalConfigPath()) || {};
+}
+function readBaselineInfo(cwd) {
+  let path = join(cwd, '.vizzly', 'baselines');
+  let metadata = readJsonFile(join(path, 'metadata.json'));
+  return {
+    count: metadata?.screenshots?.length || 0,
+    path: metadata ? path : null
+  };
+}
+function readServerInfo(cwd) {
+  let serverInfo = readJsonFile(join(cwd, '.vizzly', 'server.json'));
+  return {
+    running: !!serverInfo,
+    port: serverInfo ? serverInfo.port : null
+  };
+}
 
 /**
  * Get dynamic context about the current Vizzly state
@@ -22,46 +53,12 @@ export function getContext() {
   let items = [];
   try {
     let cwd = process.cwd();
-    let globalConfigPath = join(process.env.VIZZLY_HOME || join(homedir(), '.vizzly'), 'config.json');
-
-    // Load global config once
-    let globalConfig = {};
-    try {
-      if (existsSync(globalConfigPath)) {
-        globalConfig = JSON.parse(readFileSync(globalConfigPath, 'utf8'));
-      }
-    } catch {
-      // Ignore
-    }
+    let globalConfig = readGlobalConfig();
 
     // Check for vizzly.config.js (project config)
     let hasProjectConfig = existsSync(join(cwd, 'vizzly.config.js'));
-
-    // Check for .vizzly directory (TDD baselines)
-    let baselineCount = 0;
-    try {
-      let metaPath = join(cwd, '.vizzly', 'baselines', 'metadata.json');
-      if (existsSync(metaPath)) {
-        let meta = JSON.parse(readFileSync(metaPath, 'utf8'));
-        baselineCount = meta.screenshots?.length || 0;
-      }
-    } catch {
-      // Ignore
-    }
-
-    // Check for TDD server running
-    let serverRunning = false;
-    let serverPort = null;
-    try {
-      let serverFile = join(cwd, '.vizzly', 'server.json');
-      if (existsSync(serverFile)) {
-        let serverInfo = JSON.parse(readFileSync(serverFile, 'utf8'));
-        serverPort = serverInfo.port;
-        serverRunning = true;
-      }
-    } catch {
-      // Ignore
-    }
+    let baselineInfo = readBaselineInfo(cwd);
+    let serverInfo = readServerInfo(cwd);
 
     // Check for OAuth login (from vizzly login)
     let isLoggedIn = !!globalConfig.auth?.accessToken;
@@ -71,11 +68,11 @@ export function getContext() {
     let hasEnvToken = !!process.env.VIZZLY_TOKEN;
 
     // Build context items - prioritize most useful info
-    if (serverRunning) {
+    if (serverInfo.running) {
       items.push({
         type: 'success',
         label: 'TDD Server',
-        value: `running on :${serverPort}`
+        value: `running on :${serverInfo.port}`
       });
     }
     if (isLoggedIn && userName) {
@@ -97,14 +94,14 @@ export function getContext() {
         value: 'run vizzly login'
       });
     }
-    if (baselineCount > 0) {
+    if (baselineInfo.count > 0) {
       items.push({
         type: 'success',
         label: 'Baselines',
-        value: `${baselineCount} screenshots`
+        value: `${baselineInfo.count} screenshots`
       });
     }
-    if (!hasProjectConfig && !serverRunning && baselineCount === 0) {
+    if (!hasProjectConfig && !serverInfo.running && baselineInfo.count === 0) {
       // Only show "no config" hint if there's nothing else useful
       items.push({
         type: 'info',
@@ -126,7 +123,6 @@ export function getContext() {
  */
 export function getDetailedContext() {
   let cwd = process.cwd();
-  let globalConfigPath = join(process.env.VIZZLY_HOME || join(homedir(), '.vizzly'), 'config.json');
   let context = {
     tddServer: {
       running: false,
@@ -146,42 +142,16 @@ export function getDetailedContext() {
     }
   };
   try {
-    // Load global config
-    let globalConfig = {};
-    try {
-      if (existsSync(globalConfigPath)) {
-        globalConfig = JSON.parse(readFileSync(globalConfigPath, 'utf8'));
-      }
-    } catch {
-      // Ignore
-    }
+    let globalConfig = readGlobalConfig();
 
     // Check for vizzly.config.js
     context.project.hasConfig = existsSync(join(cwd, 'vizzly.config.js'));
-
-    // Check for baselines
-    try {
-      let metaPath = join(cwd, '.vizzly', 'baselines', 'metadata.json');
-      if (existsSync(metaPath)) {
-        let meta = JSON.parse(readFileSync(metaPath, 'utf8'));
-        context.baselines.count = meta.screenshots?.length || 0;
-        context.baselines.path = join(cwd, '.vizzly', 'baselines');
-      }
-    } catch {
-      // Ignore
-    }
-
-    // Check for TDD server
-    try {
-      let serverFile = join(cwd, '.vizzly', 'server.json');
-      if (existsSync(serverFile)) {
-        let serverInfo = JSON.parse(readFileSync(serverFile, 'utf8'));
-        context.tddServer.running = true;
-        context.tddServer.port = serverInfo.port;
-      }
-    } catch {
-      // Ignore
-    }
+    let baselineInfo = readBaselineInfo(cwd);
+    context.baselines.count = baselineInfo.count;
+    context.baselines.path = baselineInfo.path;
+    let serverInfo = readServerInfo(cwd);
+    context.tddServer.running = serverInfo.running;
+    context.tddServer.port = serverInfo.port;
 
     // Check auth status
     context.auth.loggedIn = !!globalConfig.auth?.accessToken;

package/dist/utils/environment-config.js

@@ -85,6 +85,24 @@ export function getBuildName() {
   return process.env.VIZZLY_BUILD_NAME;
 }
 
+/**
+ * Get comparison threshold from environment
+ * @returns {number|undefined} Threshold value when set
+ */
+export function getThreshold() {
+  if (process.env.VIZZLY_THRESHOLD === undefined) return undefined;
+  return Number(process.env.VIZZLY_THRESHOLD);
+}
+
+/**
+ * Get minimum changed cluster size from environment
+ * @returns {number|undefined} Minimum cluster size when set
+ */
+export function getMinClusterSize() {
+  if (process.env.VIZZLY_MIN_CLUSTER_SIZE === undefined) return undefined;
+  return Number(process.env.VIZZLY_MIN_CLUSTER_SIZE);
+}
+
 /**
  * Check if TDD mode is enabled
  * @returns {boolean} Whether TDD mode is enabled
@@ -117,6 +135,8 @@ export function getAllEnvironmentConfig() {
     buildId: getBuildId(),
     buildName: getBuildName(),
     parallelId: getParallelId(),
+    threshold: getThreshold(),
+    minClusterSize: getMinClusterSize(),
     tddMode: isTddMode()
   };
 }

package/dist/utils/output.js

@@ -282,7 +282,7 @@ export function success(message, data = {}) {
   });
   if (config.silent) return;
   if (config.json) {
-    console.log(JSON.stringify({
+    console.error(JSON.stringify({
       status: 'success',
       message,
       ...data
@@ -301,7 +301,7 @@ export function result(message) {
   if (config.silent) return;
   const elapsed = getElapsedTime();
   if (config.json) {
-    console.log(JSON.stringify({
+    console.error(JSON.stringify({
       status: 'complete',
       message,
       elapsed
@@ -319,7 +319,7 @@ export function info(message, data = {}) {
   writeLog('info', message, data);
   if (!shouldLog('info')) return;
   if (config.json) {
-    console.log(JSON.stringify({
+    console.error(JSON.stringify({
       status: 'info',
       message,
       ...data
@@ -513,7 +513,7 @@ export function stopSpinner() {
 export function progress(message, current = 0, total = 0) {
   if (config.silent) return;
   if (config.json) {
-    console.log(JSON.stringify({
+    console.error(JSON.stringify({
       status: 'progress',
       message,
       progress: {
@@ -941,7 +941,7 @@ export function complete(message, options = {}) {
   } = options;
   let detailStr = detail ? ` ${colors.brand.textMuted(detail)}` : '';
   if (config.json) {
-    console.log(JSON.stringify({
+    console.error(JSON.stringify({
       status: 'complete',
       message,
       detail

package/dist/utils/screenshot-options.js

@@ -1,21 +1,63 @@
+/**
+ * Screenshot option names that are part of the SDK/config contract, not the
+ * user's arbitrary metadata bag.
+ */
+export let RESERVED_PROPERTY_OPTIONS = Object.freeze({
+  threshold: {
+    message: 'Move "threshold" out of properties; properties is only for user metadata.'
+  },
+  minClusterSize: {
+    message: 'Move "minClusterSize" out of properties; properties is only for user metadata.'
+  },
+  fullPage: {
+    message: 'Move "fullPage" out of properties; properties is only for user metadata.'
+  },
+  buildId: {
+    message: 'Move "buildId" out of properties; properties is only for user metadata.'
+  },
+  requestTimeout: {
+    message: 'Move "requestTimeout" out of properties; properties is only for user metadata.'
+  }
+});
+function createReservedPropertyWarning(option) {
+  return {
+    code: 'reserved-property-option',
+    option,
+    message: RESERVED_PROPERTY_OPTIONS[option].message
+  };
+}
+
 /**
  * Normalize screenshot SDK options into the properties payload consumed by the
  * local TDD server and cloud-compatible comparison path.
  */
-export function createScreenshotProperties(options = {}) {
+export function normalizeScreenshotOptions(options = {}) {
   let {
-    buildId: _buildId,
+    buildId,
     properties = {},
-    requestTimeout: _requestTimeout,
+    requestTimeout,
     threshold,
     minClusterSize,
-    fullPage,
-    ...topLevelProperties
+    fullPage
   } = options;
-  let normalizedProperties = {
-    ...topLevelProperties,
-    ...properties
-  };
+  let warnings = [];
+  let normalizedProperties = {};
+  for (let [key, value] of Object.entries(properties || {})) {
+    if (RESERVED_PROPERTY_OPTIONS[key]) {
+      warnings.push(createReservedPropertyWarning(key));
+      if (key === 'threshold' && threshold === undefined) threshold = value;
+      if (key === 'minClusterSize' && minClusterSize === undefined) {
+        minClusterSize = value;
+      }
+      if (key === 'fullPage' && fullPage === undefined) fullPage = value;
+      if (key === 'buildId' && buildId === undefined) buildId = value;
+      if (key === 'requestTimeout' && requestTimeout === undefined) {
+        requestTimeout = value;
+      }
+      continue;
+    }
+    normalizedProperties[key] = value;
+  }
   if (threshold !== undefined) {
     normalizedProperties.threshold = threshold;
   }
@@ -25,5 +67,13 @@ export function createScreenshotProperties(options = {}) {
   if (fullPage !== undefined) {
     normalizedProperties.fullPage = fullPage;
   }
-  return normalizedProperties;
+  return {
+    buildId,
+    requestTimeout,
+    properties: normalizedProperties,
+    warnings
+  };
+}
+export function createScreenshotProperties(options = {}) {
+  return normalizeScreenshotOptions(options).properties;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",
@@ -55,6 +55,7 @@
     "bin",
     "dist",
     "docs/assets",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/vizzly/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: vizzly
+description: "Use when a repo has Vizzly configured and you need screenshot memory or visual history: before/after UI changes, visual regression review, screenshot history, approved baselines, diffs, dynamic regions, docs/manual images, public screenshots, or Vizzly builds. Teaches agents to use Vizzly CLI/context for local TDD, cloud builds, review state, comments, hotspots, previews, and SDK capture patterns."
+---
+
+# Vizzly
+
+Vizzly is the project's screenshot memory database. It stores approved baselines, current screenshots, diffs, review state, comments, hotspots, previews, and public screenshot URLs.
+
+Use Vizzly when you need to understand what the UI looked like before, what changed, what humans already reviewed, or which screenshots already exist. Browser automation is still useful for interacting with a live app; Vizzly is usually the faster first stop for visual history.
+
+## First Instinct
+
+Before changing UI, check whether Vizzly already has local screenshot context:
+
+```bash
+vizzly context build current --source local --agent
+```
+
+If a task names a screen, component, or screenshot, inspect that screenshot's history before changing thresholds or re-capturing blindly:
+
+```bash
+vizzly context screenshot "<screenshot-name>" --source local --json
+```
+
+When you make or verify UI changes, run the focused user workflow that owns the surface:
+
+```bash
+vizzly tdd run "<test command>" --no-open
+```
+
+Then inspect what changed:
+
+```bash
+vizzly context build current --source local --agent --json
+```
+
+For specific evidence, drill in:
+
+```bash
+vizzly context comparison <comparison-id> --json
+vizzly context screenshot "<screenshot-name>" --json
+vizzly context review-queue --json
+```
+
+If local context is unavailable and the project uses cloud builds, use the build id from CI or CLI output:
+
+```bash
+vizzly context build <build-id> --agent --json --include diffs,comments
+```
+
+## What Vizzly Knows
+
+- **Approved baselines**: expected UI.
+- **Current screenshots**: what the latest run rendered.
+- **Diffs**: where pixels/layout/content changed.
+- **Review state and comments**: human context attached to builds and screenshots.
+- **Hotspots and confirmed regions**: known dynamic areas.
+- **Preview links**: static or deployed UI context for a build.
+- **Public screenshots**: stable URLs for documentation and manuals.
+
+## Acting On Visual Context
+
+- Treat approved baselines as visual truth.
+- Treat diffs as evidence, not as approval instructions.
+- Do not approve or reject visual changes unless the user explicitly asks.
+- Prefer existing E2E or user journeys over narrow screenshot-only specs.
+- For dynamic content, inspect screenshot context before changing thresholds.
+- Prefer deterministic test data, per-screenshot `threshold`, per-screenshot `minClusterSize`, hotspots, or confirmed regions over global tolerance changes.
+- Report visual findings with screenshot names, build/comparison links when available, and the command you ran.
+
+## Capturing Screenshots
+
+Use the existing integration when one is present. For direct JavaScript capture:
+
+```javascript
+import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+
+let screenshot = await page.screenshot();
+await vizzlyScreenshot('checkout-form', screenshot, {
+  properties: {
+    browser: 'chromium',
+    viewport: 'desktop',
+    state: 'valid-card'
+  },
+  threshold: 2,
+  minClusterSize: 4
+});
+```
+
+Use `properties` to separate variants such as theme, locale, viewport, role, state, component, page, or docs/manual grouping.
+
+## When You Need More Detail
+
+- For SDK examples and capture patterns, read `references/sdks.md`.
+- For CLI/context commands and JSON output, read `references/cli-context.md`.
+- For dynamic content, thresholds, and hotspots, read `references/dynamic-content.md`.
+- For public screenshot URLs and docs/manual images, read `references/public-screenshots.md`.
+- For project setup and CI, read `references/setup-ci.md`.

package/skills/vizzly/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Vizzly"
+  short_description: "Use Vizzly visual context while changing UI."
+  default_prompt: "Use Vizzly to inspect visual context before and after UI changes."

package/skills/vizzly/references/cli-context.md

@@ -0,0 +1,42 @@
+# CLI And Context
+
+Use these commands to gather Vizzly evidence before making UI assumptions.
+
+## Local TDD
+
+```bash
+vizzly tdd start
+vizzly tdd run "<test command>" --no-open
+vizzly context build current --source local --agent
+vizzly context build current --source local --agent --json
+```
+
+Local context reads `.vizzly` state and does not require cloud auth.
+
+## Cloud Builds
+
+```bash
+export VIZZLY_TOKEN="project-token"
+vizzly run "<test command>" --wait --json
+vizzly context build <build-id> --agent --json --include diffs,comments
+```
+
+`vizzly run --wait --json` returns a `contextCommand` when a cloud build is created. Prefer that command over constructing URLs by hand.
+
+## Drilldowns
+
+```bash
+vizzly context comparison <comparison-id> --json
+vizzly context screenshot "<screenshot-name>" --json
+vizzly context similar <fingerprint-hash> --json
+vizzly context review-queue --json
+```
+
+Use comparison context for one diff. Use screenshot context for history and recurring dynamic areas. Use review queue context when triaging unresolved visual work.
+
+## Good Agent Behavior
+
+- Use `--json` for automation and summaries.
+- Use `--agent` when building prompt context or asking another agent to continue.
+- Keep human-readable command output in final summaries only when it changes the user's next action.
+- Do not approve/reject unless explicitly asked.

package/skills/vizzly/references/dynamic-content.md

@@ -0,0 +1,44 @@
+# Dynamic Content
+
+Dynamic content is common: dates, calendars, generated images, avatars, timers, randomized data, responsive text, and API-backed content.
+
+## Order Of Operations
+
+1. Make test data deterministic when the changing content is not what you are testing.
+2. Inspect screenshot context before changing code:
+
+```bash
+vizzly context screenshot "<screenshot-name>" --json
+```
+
+3. Use per-screenshot tolerances for local noise:
+
+```javascript
+await vizzlyScreenshot('plant-calendar', screenshot, {
+  properties: { surface: 'calendar' },
+  threshold: 4,
+  minClusterSize: 12
+});
+```
+
+4. Use hotspots or confirmed regions for recurring valid dynamic regions.
+
+## Avoid
+
+- Raising global project thresholds for one dynamic area.
+- Masking a whole page when a small region changes.
+- Treating every daily diff as product breakage.
+- Ignoring structural changes because a region is known to be dynamic.
+
+## How To Explain Findings
+
+Say whether the diff looks like:
+
+- expected dynamic content
+- deterministic fixture drift
+- real content disappearance
+- layout shift
+- screenshot timing/capture instability
+- baseline mismatch
+
+Then name the screenshot and include the relevant context command or link.

package/skills/vizzly/references/public-screenshots.md

@@ -0,0 +1,44 @@
+# Public Screenshots
+
+Public screenshots are Vizzly's path for stable image URLs in docs and manuals.
+
+Use this when a user asks for hotlinked UI screenshots, generated manual images, docs that stay current with UI, or CDN-like screenshot URLs.
+
+## Mental Model
+
+Do not use arbitrary build screenshot URLs as stable docs assets. Use Public Properties.
+
+The flow:
+
+1. Capture screenshots with stable metadata.
+2. Configure project Public Properties in Vizzly.
+3. Approve/publish the baseline build.
+4. Use the Public URLs tab to copy the stable URL.
+
+Example capture:
+
+```javascript
+await vizzlyScreenshot('watering-widget', screenshot, {
+  properties: {
+    manual: 'plant-care',
+    component: 'watering-widget',
+    viewport: 'desktop'
+  }
+});
+```
+
+Configure a Public Property like `manual=plant-care`. Vizzly publishes matching approved baseline screenshots and keeps stable URLs for each screenshot/property identity.
+
+## Good Uses
+
+- Product manuals
+- User docs
+- Component catalogs
+- In-app UI examples
+- Screenshots that should update when approved UI changes
+
+## Cautions
+
+- Public screenshots are public. Do not publish private user data, secrets, or internal-only UI.
+- A new unapproved build does not automatically become the public docs image.
+- Use stable names and properties so URLs do not churn.