@vizzly-testing/cli 0.34.0 → 0.35.1

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) {
@@ -76,6 +82,7 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
     config.userToken = userToken;
     output.debug('config', 'using user login for user-authenticated commands');
   }
+  config._configPath = result?.filepath || null;
   return config;
 }
 
@@ -109,7 +116,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

@@ -232,6 +232,9 @@ export function getLogLevel() {
 export function isVerbose() {
   return config.logLevel === 'debug';
 }
+export function isJson() {
+  return config.json;
+}
 
 /**
  * Show command header with distinctive branding
@@ -282,7 +285,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 +304,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 +322,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 +516,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 +944,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.34.0",
+  "version": "0.35.1",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",

package/skills/vizzly/SKILL.md

@@ -23,16 +23,24 @@ If a task names a screen, component, or screenshot, inspect that screenshot's hi
 vizzly context screenshot "<screenshot-name>" --source local --json
 ```
 
-When you make or verify UI changes, run the focused user workflow that owns the surface:
+When you make or verify UI changes, use the local TDD server as the active feedback loop:
 
 ```bash
-vizzly tdd run "<test command>" --no-open
+vizzly tdd start &
+npm run test:e2e -- tests/e2e/path.spec.js
+vizzly context build current --source local --agent --json
 ```
 
-Then inspect what changed:
+The user may choose whether the TDD server runs in the foreground or background. Once it is
+running, run tests normally from the repo. The SDK discovers `.vizzly/server.json`, posts
+screenshots to the active TDD server, and refreshes `.vizzly/current`, `.vizzly/diffs`, report
+data, and local context.
+
+Use `vizzly tdd run` for true one-off runs where you want the CLI to own starting the visual
+session and running the command:
 
 ```bash
-vizzly context build current --source local --agent --json
+vizzly tdd run "<test command>" --no-open
 ```
 
 For specific evidence, drill in:

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

@@ -5,13 +5,19 @@ Use these commands to gather Vizzly evidence before making UI assumptions.
 ## Local TDD
 
 ```bash
-vizzly tdd start
+vizzly tdd start --open
+vizzly tdd status
+vizzly tdd stop
 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.
+If `tdd start` prints a non-default port, pass that same port to
+`tdd status --port <port>` and `tdd stop --port <port>`.
+
+Local context reads `.vizzly` state and does not require cloud auth. After a
+one-shot `tdd run`, prefer the printed `contextCommand` before editing UI.
 
 ## Cloud Builds
 

package/skills/vizzly/references/setup-ci.md

@@ -6,11 +6,13 @@ Use Vizzly locally for fast feedback and in CI for shared review.
 
 ```bash
 vizzly init
-vizzly tdd start
+vizzly tdd start --open
 vizzly tdd run "<test command>" --no-open
 ```
 
 The local SDK discovers `.vizzly/server.json` and sends screenshots to the TDD server when it is running.
+For one-off checks, `vizzly tdd run` writes local review data under `.vizzly/`
+and prints a context command for follow-up inspection.
 
 ## Cloud Setup