@vizzly-testing/cli 0.17.0 → 0.18.0

package/dist/utils/output.js

@@ -8,14 +8,28 @@
  * Replaces both ConsoleUI and Logger with a single, simple API.
  */
 
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { createColors } from './colors.js';
-import { writeFileSync, appendFileSync, mkdirSync } from 'fs';
-import { dirname } from 'path';
+import { getLogLevel as getEnvLogLevel } from './environment-config.js';
+
+/**
+ * Log levels in order of severity (lowest to highest)
+ * debug < info < warn < error
+ */
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+const VALID_LOG_LEVELS = Object.keys(LOG_LEVELS);
 
 // Module state
-let config = {
+const config = {
   json: false,
-  verbose: false,
+  logLevel: null,
+  // null = not yet initialized, will check env var on first configure
   color: true,
   silent: false,
   logFile: null
@@ -31,23 +45,79 @@ let startTime = Date.now();
 // Track if we've shown the header
 let headerShown = false;
 
+/**
+ * Check if a given log level should be displayed based on current config
+ * @param {string} level - The level to check (debug, info, warn, error)
+ * @returns {boolean} Whether the level should be displayed
+ */
+function shouldLog(level) {
+  if (config.silent) return false;
+  // If logLevel not yet initialized, default to 'info'
+  let configLevel = config.logLevel || 'info';
+  let currentLevel = LOG_LEVELS[configLevel];
+  let targetLevel = LOG_LEVELS[level];
+  // Default to showing everything if levels are invalid
+  if (currentLevel === undefined) currentLevel = LOG_LEVELS.info;
+  if (targetLevel === undefined) targetLevel = LOG_LEVELS.debug;
+  return targetLevel >= currentLevel;
+}
+
+/**
+ * Normalize and validate log level
+ * @param {string} level - Log level to validate
+ * @returns {string} Valid log level (defaults to 'info' if invalid)
+ */
+function normalizeLogLevel(level) {
+  if (!level) return 'info';
+  let normalized = level.toLowerCase().trim();
+  return VALID_LOG_LEVELS.includes(normalized) ? normalized : 'info';
+}
+
 /**
  * Configure output settings
  * Call this once at CLI startup with global options
+ *
+ * @param {Object} options - Configuration options
+ * @param {boolean} [options.json] - Enable JSON output mode
+ * @param {string} [options.logLevel] - Log level (debug, info, warn, error)
+ * @param {boolean} [options.verbose] - Shorthand for logLevel='debug' (backwards compatible)
+ * @param {boolean} [options.color] - Enable colored output
+ * @param {boolean} [options.silent] - Suppress all output
+ * @param {string} [options.logFile] - Path to log file
+ * @param {boolean} [options.resetTimer] - Reset the start timer (default: true)
  */
 export function configure(options = {}) {
   if (options.json !== undefined) config.json = options.json;
-  if (options.verbose !== undefined) config.verbose = options.verbose;
   if (options.color !== undefined) config.color = options.color;
   if (options.silent !== undefined) config.silent = options.silent;
   if (options.logFile !== undefined) config.logFile = options.logFile;
+
+  // Determine log level with priority:
+  // 1. Explicit logLevel option (highest priority)
+  // 2. verbose flag (maps to 'debug')
+  // 3. Keep existing level if already initialized
+  // 4. VIZZLY_LOG_LEVEL env var (checked on first configure when logLevel is null)
+  // 5. Default ('info')
+  if (options.logLevel !== undefined) {
+    config.logLevel = normalizeLogLevel(options.logLevel);
+  } else if (options.verbose) {
+    config.logLevel = 'debug';
+  } else if (config.logLevel === null) {
+    // First configure call - check env var
+    let envLogLevel = getEnvLogLevel();
+    config.logLevel = normalizeLogLevel(envLogLevel);
+  }
+  // If logLevel is already set (not null) and no new option was provided, keep it
+
   colors = createColors({
     useColor: config.color
   });
 
-  // Reset state
-  startTime = Date.now();
-  headerShown = false;
+  // Reset state (optional - commands may want to preserve timer)
+  if (options.resetTimer !== false) {
+    startTime = Date.now();
+    headerShown = false;
+  }
 
   // Initialize log file if specified
   if (config.logFile) {
@@ -55,6 +125,22 @@ export function configure(options = {}) {
   }
 }
 
+/**
+ * Get current log level
+ * @returns {string} Current log level (defaults to 'info' if not initialized)
+ */
+export function getLogLevel() {
+  return config.logLevel || 'info';
+}
+
+/**
+ * Check if verbose/debug mode is enabled
+ * @returns {boolean} True if debug level is active
+ */
+export function isVerbose() {
+  return config.logLevel === 'debug';
+}
+
 /**
  * Show command header (e.g., "vizzly · tdd · local")
  * Only shows once per command execution
@@ -62,7 +148,7 @@ export function configure(options = {}) {
 export function header(command, mode = null) {
   if (config.json || config.silent || headerShown) return;
   headerShown = true;
-  let parts = ['vizzly', command];
+  const parts = ['vizzly', command];
   if (mode) parts.push(mode);
   console.error('');
   console.error(colors.dim(parts.join(' · ')));
@@ -104,7 +190,7 @@ export function success(message, data = {}) {
 export function result(message) {
   stopSpinner();
   if (config.silent) return;
-  let elapsed = getElapsedTime();
+  const elapsed = getElapsedTime();
   if (config.json) {
     console.log(JSON.stringify({
       status: 'complete',
@@ -121,7 +207,7 @@ export function result(message) {
  * Show an info message
  */
 export function info(message, data = {}) {
-  if (config.silent) return;
+  if (!shouldLog('info')) return;
   if (config.json) {
     console.log(JSON.stringify({
       status: 'info',
@@ -138,7 +224,7 @@ export function info(message, data = {}) {
  */
 export function warn(message, data = {}) {
   stopSpinner();
-  if (config.silent) return;
+  if (!shouldLog('warn')) return;
   if (config.json) {
     console.error(JSON.stringify({
       status: 'warning',
@@ -153,9 +239,13 @@ export function warn(message, data = {}) {
 /**
  * Show an error message (goes to stderr)
  * Does NOT exit - caller decides whether to exit
+ * Note: Errors are always shown regardless of log level (unless silent mode)
  */
 export function error(message, err = null, data = {}) {
   stopSpinner();
+
+  // Errors always show (unless silent), but we still check shouldLog for consistency
+  if (config.silent) return;
   if (config.json) {
     let errorData = {
       status: 'error',
@@ -168,7 +258,7 @@ export function error(message, err = null, data = {}) {
         message: err.getUserMessage ? err.getUserMessage() : err.message,
         code: err.code
       };
-      if (config.verbose) {
+      if (isVerbose()) {
         errorData.error.stack = err.stack;
       }
     }
@@ -182,7 +272,7 @@ export function error(message, err = null, data = {}) {
       if (errMessage && errMessage !== message) {
         console.error(colors.dim(errMessage));
       }
-      if (config.verbose && err.stack) {
+      if (isVerbose() && err.stack) {
         console.error(colors.dim(err.stack));
       }
     } else if (typeof err === 'string' && err) {
@@ -249,14 +339,14 @@ export function startSpinner(message) {
   if (config.json || config.silent || !process.stderr.isTTY) return;
   stopSpinner();
   spinnerMessage = message;
-  let frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
   let i = 0;
   spinnerInterval = setInterval(() => {
-    let frame = frames[i++ % frames.length];
-    let line = `${colors.cyan(frame)} ${spinnerMessage}`;
+    const frame = frames[i++ % frames.length];
+    const line = `${colors.cyan(frame)} ${spinnerMessage}`;
 
     // Clear previous line and write new one
-    process.stderr.write('\r' + ' '.repeat(lastSpinnerLine.length) + '\r');
+    process.stderr.write(`\r${' '.repeat(lastSpinnerLine.length)}\r`);
     process.stderr.write(line);
     lastSpinnerLine = line;
   }, 80);
@@ -267,7 +357,7 @@ export function startSpinner(message) {
  */
 export function updateSpinner(message, current = 0, total = 0) {
   if (config.json || config.silent || !process.stderr.isTTY) return;
-  let progressText = total > 0 ? ` (${current}/${total})` : '';
+  const progressText = total > 0 ? ` (${current}/${total})` : '';
   spinnerMessage = `${message}${progressText}`;
   if (!spinnerInterval) {
     startSpinner(spinnerMessage);
@@ -284,7 +374,7 @@ export function stopSpinner() {
 
     // Clear the spinner line
     if (process.stderr.isTTY) {
-      process.stderr.write('\r' + ' '.repeat(lastSpinnerLine.length) + '\r');
+      process.stderr.write(`\r${' '.repeat(lastSpinnerLine.length)}\r`);
     }
     lastSpinnerLine = '';
     spinnerMessage = '';
@@ -318,7 +408,7 @@ export function progress(message, current = 0, total = 0) {
  * Format elapsed time since CLI start
  */
 function getElapsedTime() {
-  let elapsed = Date.now() - startTime;
+  const elapsed = Date.now() - startTime;
   if (elapsed < 1000) {
     return `${elapsed}ms`;
   }
@@ -331,7 +421,7 @@ function getElapsedTime() {
  */
 function formatData(data) {
   if (!data || typeof data !== 'object') return '';
-  let entries = Object.entries(data).filter(([, v]) => {
+  const entries = Object.entries(data).filter(([, v]) => {
     if (v === null || v === undefined) return false;
     if (typeof v === 'string' && v === '') return false;
     if (Array.isArray(v) && v.length === 0) return false;
@@ -354,14 +444,14 @@ function formatData(data) {
 }
 
 /**
- * Log debug message with component prefix (only shown in verbose mode)
+ * Log debug message with component prefix (only shown when log level is 'debug')
  *
  * @param {string} component - Component name (e.g., 'server', 'config', 'build')
  * @param {string} message - Debug message
  * @param {Object} data - Optional data object to display inline
  */
 export function debug(component, message, data = {}) {
-  if (!config.verbose) return;
+  if (!shouldLog('debug')) return;
 
   // Handle legacy calls: debug('message') or debug('message', {data})
   if (typeof message === 'object' || message === undefined) {
@@ -406,14 +496,14 @@ function initLogFile() {
     mkdirSync(dirname(config.logFile), {
       recursive: true
     });
-    let header = {
+    const header = {
       timestamp: new Date().toISOString(),
       session_start: true,
       pid: process.pid,
       node_version: process.version,
       platform: process.platform
     };
-    writeFileSync(config.logFile, JSON.stringify(header) + '\n');
+    writeFileSync(config.logFile, `${JSON.stringify(header)}\n`);
   } catch {
     // Silently fail - don't crash CLI for logging issues
   }
@@ -421,13 +511,13 @@ function initLogFile() {
 function writeLog(level, message, data = {}) {
   if (!config.logFile) return;
   try {
-    let entry = {
+    const entry = {
       timestamp: new Date().toISOString(),
       level,
       message,
       ...data
     };
-    appendFileSync(config.logFile, JSON.stringify(entry) + '\n');
+    appendFileSync(config.logFile, `${JSON.stringify(entry)}\n`);
   } catch {
     // Silently fail
   }
@@ -442,4 +532,22 @@ function writeLog(level, message, data = {}) {
  */
 export function cleanup() {
   stopSpinner();
+}
+
+/**
+ * Reset module state to defaults (useful for testing)
+ * This resets all configuration to initial state
+ */
+export function reset() {
+  stopSpinner();
+  config.json = false;
+  config.logLevel = null;
+  config.color = true;
+  config.silent = false;
+  config.logFile = null;
+  colors = createColors({
+    useColor: config.color
+  });
+  startTime = Date.now();
+  headerShown = false;
 }

package/dist/utils/package-info.js

@@ -3,9 +3,9 @@
  * Centralized access to package.json data
  */
 
-import { readFileSync } from 'fs';
-import { dirname, join } from 'path';
-import { fileURLToPath } from 'url';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 let packageJson;

package/dist/utils/security.js

@@ -3,7 +3,7 @@
  * Protects against path traversal attacks and ensures safe file operations
  */
 
-import { resolve, normalize, isAbsolute, join } from 'path';
+import { isAbsolute, join, normalize, resolve } from 'node:path';
 import * as output from './output.js';
 
 /**
@@ -38,12 +38,12 @@ export function sanitizeScreenshotName(name, maxLength = 255, allowSlashes = fal
 
   // Allow only safe characters: alphanumeric, hyphens, underscores, dots, and optionally slashes
   // Replace other characters with underscores
-  let allowedChars = allowSlashes ? /[^a-zA-Z0-9._/-]/g : /[^a-zA-Z0-9._-]/g;
+  const allowedChars = allowSlashes ? /[^a-zA-Z0-9._/-]/g : /[^a-zA-Z0-9._-]/g;
   let sanitized = name.replace(allowedChars, '_');
 
   // Prevent names that start with dots (hidden files)
   if (sanitized.startsWith('.')) {
-    sanitized = 'file_' + sanitized;
+    sanitized = `file_${sanitized}`;
   }
 
   // Ensure we have a valid filename
@@ -69,8 +69,8 @@ export function validatePathSecurity(targetPath, workingDir) {
   }
 
   // Normalize and resolve both paths
-  let resolvedWorkingDir = resolve(normalize(workingDir));
-  let resolvedTargetPath = resolve(normalize(targetPath));
+  const resolvedWorkingDir = resolve(normalize(workingDir));
+  const resolvedTargetPath = resolve(normalize(targetPath));
 
   // Ensure the target path starts with the working directory
   if (!resolvedTargetPath.startsWith(resolvedWorkingDir)) {
@@ -93,7 +93,7 @@ export function safePath(workingDir, ...pathSegments) {
   }
 
   // Sanitize each path segment
-  let sanitizedSegments = pathSegments.map(segment => {
+  const sanitizedSegments = pathSegments.map(segment => {
     if (typeof segment !== 'string') {
       throw new Error('Path segment must be a string');
     }
@@ -104,7 +104,7 @@ export function safePath(workingDir, ...pathSegments) {
     }
     return segment;
   });
-  let targetPath = join(workingDir, ...sanitizedSegments);
+  const targetPath = join(workingDir, ...sanitizedSegments);
   return validatePathSecurity(targetPath, workingDir);
 }
 
@@ -117,13 +117,13 @@ export function validateScreenshotProperties(properties = {}) {
   if (properties === null || typeof properties !== 'object') {
     return {};
   }
-  let validated = {};
+  const validated = {};
 
   // Validate common properties with safe constraints
   if (properties.browser && typeof properties.browser === 'string') {
     try {
       // Extract browser name without version (e.g., "Chrome/139.0.7258.138" -> "Chrome")
-      let browserName = properties.browser.split('/')[0];
+      const browserName = properties.browser.split('/')[0];
       validated.browser = sanitizeScreenshotName(browserName, 50);
     } catch (error) {
       // Skip invalid browser names, don't include them
@@ -131,7 +131,7 @@ export function validateScreenshotProperties(properties = {}) {
     }
   }
   if (properties.viewport && typeof properties.viewport === 'object') {
-    let viewport = {};
+    const viewport = {};
     if (typeof properties.viewport.width === 'number' && properties.viewport.width > 0 && properties.viewport.width <= 10000) {
       viewport.width = Math.floor(properties.viewport.width);
     }
@@ -144,14 +144,14 @@ export function validateScreenshotProperties(properties = {}) {
   }
 
   // Allow other safe string properties but sanitize them
-  for (let [key, value] of Object.entries(properties)) {
+  for (const [key, value] of Object.entries(properties)) {
     if (key === 'browser' || key === 'viewport') continue; // Already handled
 
     if (typeof key === 'string' && key.length <= 50 && /^[a-zA-Z0-9_-]+$/.test(key)) {
       if (typeof value === 'string' && value.length <= 200) {
         // Store sanitized version of string values
         validated[key] = value.replace(/[<>&"']/g, ''); // Basic HTML entity prevention
-      } else if (typeof value === 'number' && !isNaN(value) && isFinite(value)) {
+      } else if (typeof value === 'number' && !Number.isNaN(value) && Number.isFinite(value)) {
         validated[key] = value;
       } else if (typeof value === 'boolean') {
         validated[key] = value;

package/docs/api-reference.md

@@ -613,7 +613,8 @@ Available on all commands:
 
 - `-c, --config <path>` - Config file path
 - `--token <token>` - Vizzly API token
-- `-v, --verbose` - Verbose output
+- `-v, --verbose` - Verbose output (shorthand for `--log-level debug`)
+- `--log-level <level>` - Log level: `debug`, `info`, `warn`, `error` (default: `info`, or `VIZZLY_LOG_LEVEL` env var)
 - `--json` - Machine-readable JSON output
 - `--no-color` - Disable colored output
 
@@ -661,43 +662,71 @@ Configuration loaded via cosmiconfig in this order:
 
   // Comparison Configuration
   comparison: {
-    threshold: number         // CIEDE2000 Delta E (default: 2.0)
+    threshold: number,        // CIEDE2000 Delta E (default: 2.0)
+    minClusterSize: number    // Min cluster size for noise filtering (default: 2)
   }
 }
 ```
 
 ### Environment Variables
 
-**Authentication:**
-- `VIZZLY_TOKEN` - API authentication token (project token or access token)
-  - For local development: Use `vizzly login` instead of manually managing tokens
-  - For CI/CD: Use project tokens from environment variables
-  - Token priority: CLI flag → env var → project mapping → user access token
+All Vizzly CLI behavior can be configured via environment variables. This is the complete reference.
 
-**Core Configuration:**
-- `VIZZLY_API_URL` - API base URL override (default: `https://app.vizzly.dev`)
+#### Configuration
 
-**Parallel Builds:**
-- `VIZZLY_PARALLEL_ID` - Unique identifier for parallel test execution
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `VIZZLY_HOME` | Override config directory (auth, project mappings) | `~/.vizzly` |
+| `VIZZLY_TOKEN` | API authentication token (project token `vzt_...`) | - |
+| `VIZZLY_API_URL` | API base URL | `https://app.vizzly.dev` |
+| `VIZZLY_LOG_LEVEL` | Logging verbosity: `debug`, `info`, `warn`, `error` | `info` |
 
-**Git Information Override (CI/CD Enhancement):**
-- `VIZZLY_COMMIT_SHA` - Override detected commit SHA
-- `VIZZLY_COMMIT_MESSAGE` - Override detected commit message
-- `VIZZLY_BRANCH` - Override detected branch name
-- `VIZZLY_PR_NUMBER` - Override detected pull request number
+**Token Priority:** CLI flag → env var → project mapping → user access token
 
-**Runtime (Set by CLI):**
-- `VIZZLY_SERVER_URL` - Screenshot server URL (set by CLI)
-- `VIZZLY_ENABLED` - Enable/disable client (set by CLI)
-- `VIZZLY_BUILD_ID` - Current build ID (set by CLI)
-- `VIZZLY_TDD_MODE` - TDD mode active (set by CLI)
+#### Build & Execution
 
-**Priority Order for Git Information:**
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `VIZZLY_PARALLEL_ID` | Unique identifier for parallel test shards | - |
+| `VIZZLY_BUILD_ID` | Build identifier for grouping screenshots | Auto-generated |
+
+#### Git Information Overrides
+
+Use these in CI/CD to override auto-detected git metadata:
+
+| Variable | Description |
+|----------|-------------|
+| `VIZZLY_COMMIT_SHA` | Commit SHA |
+| `VIZZLY_COMMIT_MESSAGE` | Commit message |
+| `VIZZLY_BRANCH` | Branch name |
+| `VIZZLY_PR_NUMBER` | Pull request number |
+| `VIZZLY_PR_BASE_REF` | PR base branch name |
+| `VIZZLY_PR_BASE_SHA` | PR base commit SHA |
+| `VIZZLY_PR_HEAD_REF` | PR head branch name |
+| `VIZZLY_PR_HEAD_SHA` | PR head commit SHA |
+
+**Priority Order:**
 1. CLI arguments (`--commit`, `--branch`, `--message`)
 2. `VIZZLY_*` environment variables
-3. CI-specific environment variables (e.g., `GITHUB_SHA`, `CI_COMMIT_SHA`)
+3. CI-specific variables (e.g., `GITHUB_SHA`, `CI_COMMIT_SHA`)
 4. Git command detection
 
+#### Runtime (Set by CLI)
+
+These are set automatically when running `vizzly run` or `vizzly tdd`:
+
+| Variable | Description |
+|----------|-------------|
+| `VIZZLY_ENABLED` | `true` when Vizzly capture is active |
+| `VIZZLY_SERVER_URL` | Local screenshot server URL |
+| `VIZZLY_TDD` | `true` when TDD mode is active |
+
+#### Advanced
+
+| Variable | Description |
+|----------|-------------|
+| `VIZZLY_USER_AGENT` | Custom User-Agent string for API requests |
+
 ## Error Handling
 
 ### Client Errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -71,10 +71,12 @@
     "test:watch": "vitest",
     "test:reporter": "playwright test --config=tests/reporter/playwright.config.js",
     "test:reporter:visual": "node bin/vizzly.js run \"npm run test:reporter\"",
-    "lint": "eslint src tests",
-    "lint:fix": "eslint src tests --fix",
-    "format": "prettier --write src tests",
-    "format:check": "prettier --check src tests"
+    "lint": "biome lint src tests",
+    "lint:fix": "biome lint --write src tests",
+    "format": "biome format --write src tests",
+    "format:check": "biome format src tests",
+    "check": "biome check src tests",
+    "check:fix": "biome check --write src tests"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -84,7 +86,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@vizzly-testing/honeydiff": "^0.5.0",
+    "@vizzly-testing/honeydiff": "^0.6.0",
     "commander": "^14.0.0",
     "cosmiconfig": "^9.0.0",
     "dotenv": "^17.2.1",
@@ -108,7 +110,7 @@
     "@babel/preset-env": "^7.23.6",
     "@babel/preset-react": "^7.27.1",
     "@babel/preset-typescript": "^7.23.6",
-    "@eslint/js": "^9.31.0",
+    "@biomejs/biome": "^2.3.8",
     "@heroicons/react": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.0.4",
     "@playwright/test": "^1.55.1",
@@ -119,13 +121,7 @@
     "@vitest/coverage-v8": "^4.0.3",
     "autoprefixer": "^10.4.21",
     "babel-plugin-transform-remove-console": "^6.9.4",
-    "eslint": "^9.31.0",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.3",
-    "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^7.0.0",
     "postcss": "^8.5.6",
-    "prettier": "^3.6.2",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "rimraf": "^6.0.1",