@vizzly-testing/cli 0.13.4 → 0.15.0

package/dist/utils/output.js

@@ -0,0 +1,445 @@
+/**
+ * Unified CLI output module
+ *
+ * Handles all console output with proper stream separation:
+ * - stdout: program output only (things you can pipe)
+ * - stderr: everything else (spinners, progress, errors, debug)
+ *
+ * Replaces both ConsoleUI and Logger with a single, simple API.
+ */
+
+import { createColors } from './colors.js';
+import { writeFileSync, appendFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+// Module state
+let config = {
+  json: false,
+  verbose: false,
+  color: true,
+  silent: false,
+  logFile: null
+};
+let colors = createColors({
+  useColor: config.color
+});
+let spinnerInterval = null;
+let spinnerMessage = '';
+let lastSpinnerLine = '';
+let startTime = Date.now();
+
+// Track if we've shown the header
+let headerShown = false;
+
+/**
+ * Configure output settings
+ * Call this once at CLI startup with global options
+ */
+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;
+  colors = createColors({
+    useColor: config.color
+  });
+
+  // Reset state
+  startTime = Date.now();
+  headerShown = false;
+
+  // Initialize log file if specified
+  if (config.logFile) {
+    initLogFile();
+  }
+}
+
+/**
+ * Show command header (e.g., "vizzly · tdd · local")
+ * Only shows once per command execution
+ */
+export function header(command, mode = null) {
+  if (config.json || config.silent || headerShown) return;
+  headerShown = true;
+  let parts = ['vizzly', command];
+  if (mode) parts.push(mode);
+  console.error('');
+  console.error(colors.dim(parts.join(' · ')));
+  console.error('');
+}
+
+/**
+ * Get current colors instance (for custom formatting)
+ */
+export function getColors() {
+  return colors;
+}
+
+// ============================================================================
+// User-facing output (what the user asked for)
+// ============================================================================
+
+/**
+ * Show a success message
+ */
+export function success(message, data = {}) {
+  stopSpinner();
+  if (config.silent) return;
+  if (config.json) {
+    console.log(JSON.stringify({
+      status: 'success',
+      message,
+      ...data
+    }));
+  } else {
+    console.error('');
+    console.error(colors.green('✓'), message);
+  }
+}
+
+/**
+ * Show final result summary (e.g., "✓ 5 screenshots · 234ms")
+ */
+export function result(message) {
+  stopSpinner();
+  if (config.silent) return;
+  let elapsed = getElapsedTime();
+  if (config.json) {
+    console.log(JSON.stringify({
+      status: 'complete',
+      message,
+      elapsed
+    }));
+  } else {
+    console.error('');
+    console.error(colors.green('✓'), `${message} ${colors.dim(`· ${elapsed}`)}`);
+  }
+}
+
+/**
+ * Show an info message
+ */
+export function info(message, data = {}) {
+  if (config.silent) return;
+  if (config.json) {
+    console.log(JSON.stringify({
+      status: 'info',
+      message,
+      ...data
+    }));
+  } else {
+    console.log(colors.cyan('ℹ'), message);
+  }
+}
+
+/**
+ * Show a warning message (goes to stderr)
+ */
+export function warn(message, data = {}) {
+  stopSpinner();
+  if (config.silent) return;
+  if (config.json) {
+    console.error(JSON.stringify({
+      status: 'warning',
+      message,
+      ...data
+    }));
+  } else {
+    console.error(colors.yellow('⚠'), message);
+  }
+}
+
+/**
+ * Show an error message (goes to stderr)
+ * Does NOT exit - caller decides whether to exit
+ */
+export function error(message, err = null, data = {}) {
+  stopSpinner();
+  if (config.json) {
+    let errorData = {
+      status: 'error',
+      message,
+      ...data
+    };
+    if (err instanceof Error) {
+      errorData.error = {
+        name: err.name,
+        message: err.getUserMessage ? err.getUserMessage() : err.message,
+        code: err.code
+      };
+      if (config.verbose) {
+        errorData.error.stack = err.stack;
+      }
+    }
+    console.error(JSON.stringify(errorData));
+  } else {
+    console.error(colors.red('✖'), message);
+
+    // Show error details
+    if (err instanceof Error) {
+      let errMessage = err.getUserMessage ? err.getUserMessage() : err.message;
+      if (errMessage && errMessage !== message) {
+        console.error(colors.dim(errMessage));
+      }
+      if (config.verbose && err.stack) {
+        console.error(colors.dim(err.stack));
+      }
+    } else if (typeof err === 'string' && err) {
+      console.error(colors.dim(err));
+    }
+  }
+
+  // Write to log file
+  writeLog('error', message, {
+    error: err?.message,
+    ...data
+  });
+}
+
+/**
+ * Print a blank line for spacing
+ */
+export function blank() {
+  if (!config.json && !config.silent) {
+    console.log('');
+  }
+}
+
+/**
+ * Print raw text without any formatting
+ */
+export function print(text) {
+  if (!config.silent) {
+    console.log(text);
+  }
+}
+
+/**
+ * Print raw text to stderr
+ */
+export function printErr(text) {
+  if (!config.silent) {
+    console.error(text);
+  }
+}
+
+/**
+ * Output structured data
+ */
+export function data(obj) {
+  if (config.json) {
+    console.log(JSON.stringify({
+      status: 'data',
+      data: obj
+    }));
+  } else {
+    console.log(JSON.stringify(obj, null, 2));
+  }
+}
+
+// ============================================================================
+// Spinner / Progress (stderr so it doesn't pollute piped output)
+// ============================================================================
+
+/**
+ * Start a spinner with message
+ */
+export function startSpinner(message) {
+  if (config.json || config.silent || !process.stderr.isTTY) return;
+  stopSpinner();
+  spinnerMessage = message;
+  let frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0;
+  spinnerInterval = setInterval(() => {
+    let frame = frames[i++ % frames.length];
+    let line = `${colors.cyan(frame)} ${spinnerMessage}`;
+
+    // Clear previous line and write new one
+    process.stderr.write('\r' + ' '.repeat(lastSpinnerLine.length) + '\r');
+    process.stderr.write(line);
+    lastSpinnerLine = line;
+  }, 80);
+}
+
+/**
+ * Update spinner message
+ */
+export function updateSpinner(message, current = 0, total = 0) {
+  if (config.json || config.silent || !process.stderr.isTTY) return;
+  let progressText = total > 0 ? ` (${current}/${total})` : '';
+  spinnerMessage = `${message}${progressText}`;
+  if (!spinnerInterval) {
+    startSpinner(spinnerMessage);
+  }
+}
+
+/**
+ * Stop the spinner
+ */
+export function stopSpinner() {
+  if (spinnerInterval) {
+    clearInterval(spinnerInterval);
+    spinnerInterval = null;
+
+    // Clear the spinner line
+    if (process.stderr.isTTY) {
+      process.stderr.write('\r' + ' '.repeat(lastSpinnerLine.length) + '\r');
+    }
+    lastSpinnerLine = '';
+    spinnerMessage = '';
+  }
+}
+
+/**
+ * Show progress update
+ */
+export function progress(message, current = 0, total = 0) {
+  if (config.silent) return;
+  if (config.json) {
+    console.log(JSON.stringify({
+      status: 'progress',
+      message,
+      progress: {
+        current,
+        total
+      }
+    }));
+  } else {
+    updateSpinner(message, current, total);
+  }
+}
+
+// ============================================================================
+// Debug logging (only when verbose, goes to stderr and/or file)
+// ============================================================================
+
+/**
+ * Format elapsed time since CLI start
+ */
+function getElapsedTime() {
+  let elapsed = Date.now() - startTime;
+  if (elapsed < 1000) {
+    return `${elapsed}ms`;
+  }
+  return `${(elapsed / 1000).toFixed(1)}s`;
+}
+
+/**
+ * Format a data object for human-readable output
+ * Only shows meaningful values, skips nulls/undefined/empty
+ */
+function formatData(data) {
+  if (!data || typeof data !== 'object') return '';
+  let 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;
+    return true;
+  });
+  if (entries.length === 0) return '';
+
+  // For simple key-value pairs, show inline
+  if (entries.length <= 4 && entries.every(([, v]) => typeof v !== 'object')) {
+    return entries.map(([k, v]) => `${k}=${v}`).join(' ');
+  }
+
+  // For complex objects, show on multiple lines
+  return entries.map(([k, v]) => {
+    if (typeof v === 'object') {
+      return `${k}: ${JSON.stringify(v)}`;
+    }
+    return `${k}: ${v}`;
+  }).join('\n');
+}
+
+/**
+ * Log debug message with component prefix (only shown in verbose mode)
+ *
+ * @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;
+
+  // Handle legacy calls: debug('message') or debug('message', {data})
+  if (typeof message === 'object' || message === undefined) {
+    data = message || {};
+    message = component;
+    component = null;
+  }
+  let elapsed = getElapsedTime();
+  if (config.json) {
+    console.error(JSON.stringify({
+      status: 'debug',
+      time: elapsed,
+      component,
+      message,
+      ...data
+    }));
+  } else {
+    let formattedData = formatData(data);
+    let dataStr = formattedData ? ` ${colors.dim(formattedData)}` : '';
+    if (component) {
+      // Component-based format: "  server    listening on :47392"
+      let paddedComponent = component.padEnd(8);
+      console.error(`  ${colors.cyan(paddedComponent)} ${message}${dataStr}`);
+    } else {
+      // Simple format for legacy calls
+      console.error(`  ${colors.dim('•')} ${colors.dim(message)}${dataStr}`);
+    }
+  }
+  writeLog('debug', message, {
+    component,
+    ...data
+  });
+}
+
+// ============================================================================
+// Log file support
+// ============================================================================
+
+function initLogFile() {
+  if (!config.logFile) return;
+  try {
+    mkdirSync(dirname(config.logFile), {
+      recursive: true
+    });
+    let 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');
+  } catch {
+    // Silently fail - don't crash CLI for logging issues
+  }
+}
+function writeLog(level, message, data = {}) {
+  if (!config.logFile) return;
+  try {
+    let entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      ...data
+    };
+    appendFileSync(config.logFile, JSON.stringify(entry) + '\n');
+  } catch {
+    // Silently fail
+  }
+}
+
+// ============================================================================
+// Cleanup
+// ============================================================================
+
+/**
+ * Clean up (stop spinner, flush logs)
+ */
+export function cleanup() {
+  stopSpinner();
+}

package/dist/utils/security.js

@@ -4,8 +4,7 @@
  */
 
 import { resolve, normalize, isAbsolute, join } from 'path';
-import { createServiceLogger } from './logger-factory.js';
-const logger = createServiceLogger('SECURITY');
+import * as output from './output.js';
 
 /**
  * Sanitizes a screenshot name to prevent path traversal and ensure safe file naming
@@ -75,7 +74,7 @@ export function validatePathSecurity(targetPath, workingDir) {
 
   // Ensure the target path starts with the working directory
   if (!resolvedTargetPath.startsWith(resolvedWorkingDir)) {
-    logger.warn(`Path traversal attempt blocked: ${targetPath} (resolved: ${resolvedTargetPath}) is outside working directory: ${resolvedWorkingDir}`);
+    output.warn(`Path traversal attempt blocked: ${targetPath} (resolved: ${resolvedTargetPath}) is outside working directory: ${resolvedWorkingDir}`);
     throw new Error('Path is outside the allowed working directory');
   }
   return resolvedTargetPath;
@@ -128,7 +127,7 @@ export function validateScreenshotProperties(properties = {}) {
       validated.browser = sanitizeScreenshotName(browserName, 50);
     } catch (error) {
       // Skip invalid browser names, don't include them
-      logger.warn(`Invalid browser name '${properties.browser}': ${error.message}`);
+      output.warn(`Invalid browser name '${properties.browser}': ${error.message}`);
     }
   }
   if (properties.viewport && typeof properties.viewport === 'object') {

package/docs/api-reference.md

@@ -676,7 +676,6 @@ Configuration loaded via cosmiconfig in this order:
 
 **Core Configuration:**
 - `VIZZLY_API_URL` - API base URL override (default: `https://app.vizzly.dev`)
-- `VIZZLY_LOG_LEVEL` - Logger level (`debug`, `info`, `warn`, `error`)
 
 **Parallel Builds:**
 - `VIZZLY_PARALLEL_ID` - Unique identifier for parallel test execution

package/docs/plugins.md

@@ -13,7 +13,7 @@ file.
 ## Benefits
 
 - **Zero Configuration** - Just `npm install` and the plugin is available
-- **Shared Infrastructure** - Plugins get access to config, logger, and services
+- **Shared Infrastructure** - Plugins get access to config, output utilities, and services
 - **Independent Releases** - Plugins can iterate without requiring CLI updates
 - **Smaller Core** - Keep the main CLI lean by moving optional features to plugins
 - **Community Extensible** - Anyone can build and share plugins
@@ -95,14 +95,14 @@ export default {
   name: 'my-plugin',
   version: '1.0.0', // Optional but recommended
 
-  register(program, { config, logger, services }) {
+  register(program, { config, output, services }) {
     // Register your command with Commander.js
     program
       .command('my-command <arg>')
       .description('Description of my command')
       .option('--option <value>', 'An option')
       .action(async (arg, options) => {
-        logger.info(`Running my-command with ${arg}`);
+        output.info(`Running my-command with ${arg}`);
 
         // Access shared services if needed
         let apiService = await services.get('apiService');
@@ -131,14 +131,13 @@ The `register` function receives two arguments:
 1. **`program`** - [Commander.js](https://github.com/tj/commander.js) program instance for registering commands
 2. **`context`** - Object containing:
    - `config` - Merged Vizzly configuration object
-   - `logger` - Shared logger instance with `.debug()`, `.info()`, `.warn()`, `.error()` methods
+   - `output` - Unified output module with `.debug()`, `.info()`, `.warn()`, `.error()`, `.success()` methods
    - `services` - Service container with access to internal Vizzly services
 
 ### Available Services
 
 Plugins can access these services from the container:
 
-- **`logger`** - Component logger for consistent output
 - **`apiService`** - Vizzly API client for interacting with the platform
 - **`uploader`** - Screenshot upload service
 - **`buildManager`** - Build lifecycle management
@@ -149,7 +148,7 @@ Plugins can access these services from the container:
 Example accessing a service:
 
 ```javascript
-register(program, { config, logger, services }) {
+register(program, { config, output, services }) {
   program
     .command('upload-screenshots <dir>')
     .action(async (dir) => {
@@ -177,12 +176,12 @@ touch plugins/my-plugin.js
 export default {
   name: 'my-plugin',
   version: '1.0.0',
-  register(program, { config, logger }) {
+  register(program, { config, output }) {
     program
       .command('greet <name>')
       .description('Greet someone')
       .action((name) => {
-        logger.info(`Hello, ${name}!`);
+        output.info(`Hello, ${name}!`);
       });
   }
 };
@@ -255,33 +254,34 @@ export default {
 Always handle errors gracefully and provide helpful error messages:
 
 ```javascript
-register(program, { logger }) {
+register(program, { output }) {
   program
     .command('process <file>')
     .action(async (file) => {
       try {
         if (!existsSync(file)) {
-          logger.error(`File not found: ${file}`);
+          output.error(`File not found: ${file}`);
           process.exit(1);
         }
         // Process file...
       } catch (error) {
-        logger.error(`Failed to process file: ${error.message}`);
+        output.error(`Failed to process file: ${error.message}`);
         process.exit(1);
       }
     });
 }
 ```
 
-### Logging
+### Output
 
-Use the provided logger for consistent output across all CLI commands:
+Use the provided output module for consistent CLI output:
 
 ```javascript
-logger.debug('Detailed debug info');   // Only shown with --verbose
-logger.info('Normal information');     // Standard output
-logger.warn('Warning message');        // Warning output
-logger.error('Error message');         // Error output
+output.debug('Detailed debug info');   // Only shown with --verbose (stderr)
+output.info('Normal information');     // Info messages (stdout)
+output.success('Completed!');          // Success messages (stdout)
+output.warn('Warning message');        // Warning messages (stderr)
+output.error('Error message');         // Error messages (stderr)
 ```
 
 ### Async Operations
@@ -292,7 +292,7 @@ Use async/await for asynchronous operations:
 .action(async (options) => {
   let service = await services.get('apiService');
   let result = await service.doSomething();
-  logger.info(`Result: ${result}`);
+  output.info(`Result: ${result}`);
 });
 ```
 
@@ -318,13 +318,13 @@ Validate user input and provide helpful error messages:
 ```javascript
 .action(async (path, options) => {
   if (!path) {
-    logger.error('Path is required');
+    output.error('Path is required');
     process.exit(1);
   }
 
   if (!existsSync(path)) {
-    logger.error(`Path not found: ${path}`);
-    logger.info('Please provide a valid path to your build directory');
+    output.error(`Path not found: ${path}`);
+    output.info('Please provide a valid path to your build directory');
     process.exit(1);
   }
 
@@ -337,7 +337,7 @@ Validate user input and provide helpful error messages:
 Import heavy dependencies only when needed to keep CLI startup fast:
 
 ```javascript
-register(program, { logger }) {
+register(program, { output }) {
   program
     .command('process-images <dir>')
     .action(async (dir) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.13.4",
+  "version": "0.15.0",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -84,7 +84,7 @@
     "cosmiconfig": "^9.0.0",
     "dotenv": "^17.2.1",
     "form-data": "^4.0.0",
-    "glob": "^11.0.3",
+    "glob": "^13.0.0",
     "zod": "^4.1.12"
   },
   "devDependencies": {
@@ -98,6 +98,7 @@
     "@modelcontextprotocol/sdk": "^1.0.4",
     "@playwright/test": "^1.55.1",
     "@tailwindcss/postcss": "^4.1.13",
+    "@tanstack/react-query": "^5.90.11",
     "@vitejs/plugin-react": "^5.0.3",
     "@vitest/coverage-v8": "^4.0.3",
     "autoprefixer": "^10.4.21",