@vizzly-testing/cli 0.20.1-beta.0 → 0.20.1

package/README.md

@@ -238,13 +238,13 @@ vizzly run "npm test" --parallel-id "ci-run-123"  # For parallel CI builds
 - `--allow-no-token` - Allow running without API token (useful for local development)
 - `--token <token>` - API token override
 
-## Dev Command
+## TDD Command
 
-For local development with visual testing, use the `dev` command:
+For local development with visual testing, use the `tdd` command:
 
 ```bash
-# Start interactive dev server (runs in background)
-vizzly dev start
+# Start TDD server (runs in background)
+vizzly tdd start
 
 # Run your tests in watch mode (same terminal or new one)
 npm test -- --watch
@@ -252,7 +252,7 @@ npm test -- --watch
 # View the dashboard at http://localhost:47392
 ```
 
-**Interactive Dashboard:** The dev dashboard provides real-time feedback:
+**Interactive Dashboard:** The TDD dashboard provides real-time feedback:
 - **Visual Comparisons** - See diffs as tests run with multiple view modes
 - **Baseline Management** - Accept/reject changes directly from the UI
 - **Configuration Editor** - Edit settings without touching config files
@@ -260,23 +260,23 @@ npm test -- --watch
 - **Test Statistics** - Real-time pass/fail metrics
 - **Dark Theme** - Easy on the eyes during long sessions
 
-**Dev Subcommands:**
+**TDD Subcommands:**
 
 ```bash
-# Start the dev server (primary workflow)
-vizzly dev start [options]
+# Start the TDD server (primary workflow)
+vizzly tdd start [options]
 
 # Run tests once with ephemeral server (generates static report)
-vizzly dev run "npm test" [options]
+vizzly tdd run "npm test" [options]
 
-# Check dev server status
-vizzly dev status
+# Check TDD server status
+vizzly tdd status
 
-# Stop a running dev server
-vizzly dev stop
+# Stop a running TDD server
+vizzly tdd stop
 ```
 
-**Dev Command Options:**
+**TDD Command Options:**
 - `--set-baseline` - Accept current screenshots as new baseline
 - `--baseline-build <id>` - Use specific build as baseline (requires API token)
 - `--threshold <number>` - Comparison threshold (CIEDE2000 Delta E, default: 2.0)
@@ -340,10 +340,8 @@ VIZZLY_TOKEN=your-token vizzly doctor --api
 vizzly doctor --json
 ```
 
-The `dev` command provides fast local development with immediate visual feedback. See the
-[Dev Mode Guide](./docs/dev-mode.md) for complete details on local visual testing.
-
-> **Note:** The `vizzly tdd` command is deprecated and will be removed in the next major version. Please use `vizzly dev` instead.
+The `tdd` command provides fast local development with immediate visual feedback. See the
+[TDD Mode Guide](./docs/tdd-mode.md) for complete details on local visual testing.
 
 ## Configuration
 

package/dist/cli.js

@@ -16,10 +16,178 @@ import { validateWhoamiOptions, whoamiCommand } from './commands/whoami.js';
 import { createPluginServices } from './plugin-api.js';
 import { loadPlugins } from './plugin-loader.js';
 import { createServices } from './services/index.js';
+import { colors } from './utils/colors.js';
 import { loadConfig } from './utils/config-loader.js';
+import { getContext } from './utils/context.js';
 import * as output from './utils/output.js';
 import { getPackageVersion } from './utils/package-info.js';
-program.name('vizzly').description('Vizzly CLI for visual regression testing').version(getPackageVersion()).option('-c, --config <path>', 'Config file path').option('--token <token>', 'Vizzly API token').option('-v, --verbose', 'Verbose output (shorthand for --log-level debug)').option('--log-level <level>', 'Log level: debug, info, warn, error (default: info, or VIZZLY_LOG_LEVEL env var)').option('--json', 'Machine-readable output').option('--no-color', 'Disable colored output');
+
+// Custom help formatting with Observatory design system
+const formatHelp = (cmd, helper) => {
+  let c = colors;
+  let lines = [];
+  let isRootCommand = !cmd.parent;
+  let version = getPackageVersion();
+
+  // Branded header with grizzly bear
+  lines.push('');
+  if (isRootCommand) {
+    // Cute grizzly bear mascot with square eyes (like the Vizzly logo!)
+    lines.push(c.brand.amber('   ʕ□ᴥ□ʔ'));
+    lines.push(`   ${c.brand.amber(c.bold('vizzly'))} ${c.dim(`v${version}`)}`);
+    lines.push(`   ${c.gray('Visual regression testing for UI teams')}`);
+  } else {
+    // Compact header for subcommands
+    lines.push(`  ${c.brand.amber(c.bold('vizzly'))} ${c.white(cmd.name())}`);
+    let desc = cmd.description();
+    if (desc) {
+      lines.push(`  ${c.gray(desc)}`);
+    }
+  }
+  lines.push('');
+
+  // Usage
+  let usage = helper.commandUsage(cmd).replace('Usage: ', '');
+  lines.push(`  ${c.dim('Usage')}  ${c.white(usage)}`);
+  lines.push('');
+
+  // Get all subcommands
+  let commands = helper.visibleCommands(cmd);
+  if (commands.length > 0) {
+    if (isRootCommand) {
+      // Group commands by category for root help with icons
+      let categories = [{
+        key: 'core',
+        icon: '▸',
+        title: 'Core',
+        names: ['run', 'tdd', 'upload', 'status', 'finalize']
+      }, {
+        key: 'setup',
+        icon: '▸',
+        title: 'Setup',
+        names: ['init', 'doctor']
+      }, {
+        key: 'auth',
+        icon: '▸',
+        title: 'Account',
+        names: ['login', 'logout', 'whoami']
+      }, {
+        key: 'project',
+        icon: '▸',
+        title: 'Projects',
+        names: ['project:select', 'project:list', 'project:token', 'project:remove']
+      }];
+      let grouped = {
+        core: [],
+        setup: [],
+        auth: [],
+        project: [],
+        other: []
+      };
+      for (let command of commands) {
+        let name = command.name();
+        if (name === 'help') continue;
+        let found = false;
+        for (let cat of categories) {
+          if (cat.names.includes(name)) {
+            grouped[cat.key].push(command);
+            found = true;
+            break;
+          }
+        }
+        if (!found) grouped.other.push(command);
+      }
+      for (let cat of categories) {
+        let cmds = grouped[cat.key];
+        if (cmds.length === 0) continue;
+        lines.push(`  ${c.brand.amber(cat.icon)} ${c.bold(cat.title)}`);
+        for (let command of cmds) {
+          let name = command.name();
+          let desc = command.description() || '';
+          // Truncate long descriptions
+          if (desc.length > 48) desc = `${desc.substring(0, 45)}...`;
+          lines.push(`      ${c.white(name.padEnd(18))} ${c.gray(desc)}`);
+        }
+        lines.push('');
+      }
+
+      // Plugins (other commands from plugins)
+      if (grouped.other.length > 0) {
+        lines.push(`  ${c.brand.amber('▸')} ${c.bold('Plugins')}`);
+        for (let command of grouped.other) {
+          let name = command.name();
+          let desc = command.description() || '';
+          if (desc.length > 48) desc = `${desc.substring(0, 45)}...`;
+          lines.push(`      ${c.white(name.padEnd(18))} ${c.gray(desc)}`);
+        }
+        lines.push('');
+      }
+    } else {
+      // For subcommands, simple list
+      lines.push(`  ${c.brand.amber('▸')} ${c.bold('Commands')}`);
+      for (let command of commands) {
+        let name = command.name();
+        if (name === 'help') continue;
+        let desc = command.description() || '';
+        if (desc.length > 48) desc = `${desc.substring(0, 45)}...`;
+        lines.push(`      ${c.white(name.padEnd(18))} ${c.gray(desc)}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // Options - use dimmer styling for less visual weight
+  let options = helper.visibleOptions(cmd);
+  if (options.length > 0) {
+    lines.push(`  ${c.brand.amber('▸')} ${c.bold('Options')}`);
+    for (let option of options) {
+      let flags = option.flags;
+      let desc = option.description || '';
+      if (desc.length > 40) desc = `${desc.substring(0, 37)}...`;
+      lines.push(`      ${c.cyan(flags.padEnd(22))} ${c.dim(desc)}`);
+    }
+    lines.push('');
+  }
+
+  // Quick start examples (only for root command)
+  if (isRootCommand) {
+    lines.push(`  ${c.brand.amber('▸')} ${c.bold('Quick Start')}`);
+    lines.push('');
+    lines.push(`      ${c.dim('# Local visual testing')}`);
+    lines.push(`      ${c.gray('$')} ${c.white('vizzly tdd start')}`);
+    lines.push('');
+    lines.push(`      ${c.dim('# CI pipeline')}`);
+    lines.push(`      ${c.gray('$')} ${c.white('vizzly run "npm test" --wait')}`);
+    lines.push('');
+  }
+
+  // Dynamic context section (only for root)
+  if (isRootCommand) {
+    let contextItems = getContext();
+    if (contextItems.length > 0) {
+      lines.push(`  ${c.dim('─'.repeat(52))}`);
+      for (let item of contextItems) {
+        if (item.type === 'success') {
+          lines.push(`  ${c.green('✓')} ${c.gray(item.label)}  ${c.white(item.value)}`);
+        } else if (item.type === 'warning') {
+          lines.push(`  ${c.yellow('!')} ${c.gray(item.label)}  ${c.yellow(item.value)}`);
+        } else {
+          lines.push(`  ${c.dim('○')} ${c.gray(item.label)}  ${c.dim(item.value)}`);
+        }
+      }
+      lines.push('');
+    }
+  }
+
+  // Footer with links
+  lines.push(`  ${c.dim('─'.repeat(52))}`);
+  lines.push(`  ${c.dim('Docs')} ${c.cyan(c.underline('docs.vizzly.dev'))}  ${c.dim('GitHub')} ${c.cyan(c.underline('github.com/vizzly-testing/cli'))}`);
+  lines.push('');
+  return lines.join('\n');
+};
+program.name('vizzly').description('Vizzly CLI for visual regression testing').version(getPackageVersion()).option('-c, --config <path>', 'Config file path').option('--token <token>', 'Vizzly API token').option('-v, --verbose', 'Verbose output (shorthand for --log-level debug)').option('--log-level <level>', 'Log level: debug, info, warn, error (default: info, or VIZZLY_LOG_LEVEL env var)').option('--json', 'Machine-readable output').option('--color', 'Force colored output (even in non-TTY)').option('--no-color', 'Disable colored output').configureHelp({
+  formatHelp
+});
 
 // Load plugins before defining commands
 // We need to manually parse to get the config option early
@@ -40,10 +208,17 @@ for (let i = 0; i < process.argv.length; i++) {
 
 // Configure output early
 // Priority: --log-level > --verbose > VIZZLY_LOG_LEVEL env var > default ('info')
+// Color priority: --no-color (off) > --color (on) > auto-detect
+let colorOverride;
+if (process.argv.includes('--no-color')) {
+  colorOverride = false;
+} else if (process.argv.includes('--color')) {
+  colorOverride = true;
+}
 output.configure({
   logLevel: logLevelArg,
   verbose: verboseMode,
-  color: !process.argv.includes('--no-color'),
+  color: colorOverride,
   json: process.argv.includes('--json')
 });
 const config = await loadConfig(configPath, {});

package/dist/client/index.js

@@ -4,17 +4,40 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
+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';
 
 // Internal client state
 let currentClient = null;
 let isDisabled = false;
-let hasLoggedWarning = false;
 
 // Default timeout for screenshot requests (30 seconds)
 const DEFAULT_TIMEOUT_MS = 30000;
 
+// Log levels for client SDK output control
+export const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+
+/**
+ * Check if client should log at the given level
+ * Respects VIZZLY_CLIENT_LOG_LEVEL env var (default: 'error' - only show errors)
+ * @param {string} level - Log level to check
+ * @param {string} [configuredLevel] - Configured log level (defaults to env var)
+ * @returns {boolean} Whether to log at this level
+ */
+export function shouldLogClient(level, configuredLevel) {
+  let configLevel = configuredLevel || process.env.VIZZLY_CLIENT_LOG_LEVEL?.toLowerCase() || 'error';
+  let levelValue = LOG_LEVELS[level] ?? 0;
+  let configValue = LOG_LEVELS[configLevel] ?? 3;
+  return levelValue >= configValue;
+}
+
 /**
  * Check if Vizzly is currently disabled
  * @private
@@ -28,31 +51,32 @@ function isVizzlyDisabled() {
 /**
  * Disable Vizzly SDK for the current session
  * @private
- * @param {string} [reason] - Optional reason for disabling
  */
-function disableVizzly(reason = 'disabled') {
+function disableVizzly() {
   isDisabled = true;
   currentClient = null;
-  if (reason !== 'disabled') {
-    console.warn(`Vizzly SDK disabled due to ${reason}. Screenshots will be skipped for the remainder of this session.`);
-  }
 }
 
 /**
  * Auto-discover local TDD server by checking for server.json
- * @private
+ * @param {string} [startDir] - Directory to start search from (defaults to cwd)
+ * @param {Object} [deps] - Injectable dependencies for testing
  * @returns {string|null} Server URL if found
  */
-function autoDiscoverTddServer() {
+export function autoDiscoverTddServer(startDir, deps = {}) {
+  let {
+    exists = existsSync,
+    readFile = readFileSync
+  } = deps;
   try {
     // Look for .vizzly/server.json in current directory and parent directories
-    let currentDir = process.cwd();
+    let currentDir = startDir || process.cwd();
     const root = parse(currentDir).root;
     while (currentDir !== root) {
       const serverJsonPath = join(currentDir, '.vizzly', 'server.json');
-      if (existsSync(serverJsonPath)) {
+      if (exists(serverJsonPath)) {
         try {
-          const serverInfo = JSON.parse(readFileSync(serverJsonPath, 'utf8'));
+          const serverInfo = JSON.parse(readFile(serverJsonPath, 'utf8'));
           if (serverInfo.port) {
             const url = `http://localhost:${serverInfo.port}`;
             return url;
@@ -97,6 +121,63 @@ function getClient() {
   return currentClient;
 }
 
+/**
+ * Make HTTP/HTTPS request without keep-alive (so process can exit promptly)
+ * @private
+ * @param {string} url - Full URL to POST to (http or https)
+ * @param {object} body - JSON-serializable request body
+ * @param {number} timeoutMs - Request timeout in milliseconds
+ * @returns {Promise<{status: number, json: any}>} Response status and parsed JSON body
+ */
+function httpPost(url, body, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let parsedUrl = new URL(url);
+    let data = JSON.stringify(body);
+    let isHttps = parsedUrl.protocol === 'https:';
+    let request = isHttps ? httpsRequest : httpRequest;
+    let req = request({
+      hostname: parsedUrl.hostname,
+      port: parsedUrl.port || (isHttps ? 443 : 80),
+      path: parsedUrl.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(data),
+        Connection: 'close'
+      },
+      agent: false // Disable keep-alive agent so process can exit promptly
+    }, res => {
+      let chunks = [];
+      res.on('data', chunk => chunks.push(chunk));
+      res.on('end', () => {
+        let responseBody = Buffer.concat(chunks).toString();
+        let json = null;
+        try {
+          json = JSON.parse(responseBody);
+        } catch (err) {
+          if (shouldLogClient('debug')) {
+            console.debug(`[vizzly] Failed to parse response: ${err.message}`);
+          }
+          json = {
+            error: responseBody
+          };
+        }
+        resolve({
+          status: res.statusCode,
+          json
+        });
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+    req.write(data);
+    req.end();
+  });
+}
+
 /**
  * Create a simple HTTP client for screenshots
  * @private
@@ -104,50 +185,29 @@ function getClient() {
 function createSimpleClient(serverUrl) {
   return {
     async screenshot(name, imageBuffer, options = {}) {
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
       try {
         // If it's a string, assume it's a file path and send directly
         // Otherwise it's a Buffer, so convert to base64
         const image = typeof imageBuffer === 'string' ? imageBuffer : imageBuffer.toString('base64');
-        const response = await fetch(`${serverUrl}/screenshot`, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json'
-          },
-          body: JSON.stringify({
-            buildId: getBuildId(),
-            name,
-            image,
-            properties: options,
-            fullPage: options.fullPage || false
-          }),
-          signal: controller.signal
-        });
-        if (!response.ok) {
-          const errorData = await response.json().catch(async () => {
-            const errorText = await response.text().catch(() => 'Unknown error');
-            return {
-              error: errorText
-            };
-          });
-
-          // In TDD mode, if we get 422 (visual difference), log but DON'T throw
+        const {
+          status,
+          json
+        } = await httpPost(`${serverUrl}/screenshot`, {
+          buildId: getBuildId(),
+          name,
+          image,
+          properties: options,
+          fullPage: options.fullPage || false
+        }, DEFAULT_TIMEOUT_MS);
+        if (status < 200 || status >= 300) {
+          // In TDD mode, if we get 422 (visual difference), don't throw
           // This allows all screenshots in the test to be captured and compared
-          if (response.status === 422 && errorData.tddMode && errorData.comparison) {
-            const comp = errorData.comparison;
-            const diffPercent = comp.diffPercentage ? comp.diffPercentage.toFixed(2) : '0.00';
-
-            // Extract port from serverUrl (e.g., "http://localhost:47392" -> "47392")
-            const urlMatch = serverUrl.match(/:(\d+)/);
-            const port = urlMatch ? urlMatch[1] : '47392';
-            const dashboardUrl = `http://localhost:${port}/dashboard`;
-
-            // Just log warning - don't throw by default in TDD mode
-            // This allows all screenshots to be captured
-            console.warn(`⚠️  Visual diff: ${comp.name} (${diffPercent}%) → ${dashboardUrl}`);
+          // The summary will show all failures at the end
+          if (status === 422 && json.tddMode && json.comparison) {
+            let comp = json.comparison;
 
             // Return success so test continues and captures remaining screenshots
+            // Visual diff details will be shown in the summary after tests complete
             return {
               success: true,
               status: 'failed',
@@ -155,46 +215,56 @@ function createSimpleClient(serverUrl) {
               diffPercentage: comp.diffPercentage
             };
           }
-          throw new Error(`Screenshot failed: ${response.status} ${response.statusText} - ${errorData.error || 'Unknown error'}`);
+          throw new Error(`Screenshot failed: ${status} - ${json.error || 'Unknown error'}`);
         }
-        clearTimeout(timeoutId);
-        return await response.json();
+        return json;
       } catch (error) {
-        clearTimeout(timeoutId);
-
-        // Handle timeout (AbortError)
-        if (error.name === 'AbortError') {
-          console.error(`Vizzly screenshot timed out for "${name}" after ${DEFAULT_TIMEOUT_MS / 1000}s`);
-          console.error('The server may be overloaded or unresponsive. Check server health.');
-          disableVizzly('timeout');
+        // Handle timeout
+        if (error.message === 'Request timeout') {
+          if (shouldLogClient('error')) {
+            console.error(`[vizzly] Screenshot timed out for "${name}" after ${DEFAULT_TIMEOUT_MS / 1000}s`);
+          }
+          disableVizzly();
           return null;
         }
 
         // In TDD mode with visual differences, throw the error to fail the test
         if (error.message?.toLowerCase().includes('visual diff')) {
-          // Clean output for TDD mode - don't spam with additional logs
           throw error;
         }
-        console.error(`Vizzly screenshot failed for ${name}:`, error.message);
-        if (error.message?.includes('fetch') || error.code === 'ECONNREFUSED') {
-          console.error(`Server URL: ${serverUrl}/screenshot`);
-          console.error('This usually means the Vizzly server is not running or not accessible');
-          console.error('Check that the server is started and the port is correct');
-        } else if (error.message?.includes('404') || error.message?.includes('Not Found')) {
-          console.error(`Server URL: ${serverUrl}/screenshot`);
-          console.error('The screenshot endpoint was not found - check server configuration');
+
+        // Log connection errors (these indicate setup problems)
+        if (shouldLogClient('error')) {
+          if (error.code === 'ECONNREFUSED') {
+            console.error(`[vizzly] Server not accessible at ${serverUrl}/screenshot`);
+          } else if (error.message?.includes('404') || error.message?.includes('Not Found')) {
+            console.error(`[vizzly] Screenshot endpoint not found at ${serverUrl}/screenshot`);
+          } else {
+            console.error(`[vizzly] Screenshot failed for ${name}: ${error.message}`);
+          }
         }
 
         // Disable the SDK after first failure to prevent spam
-        disableVizzly('failure');
+        disableVizzly();
 
-        // Don't throw - just return silently to not break tests (except TDD mode)
+        // Don't throw - just return silently to not break tests
         return null;
       }
     },
     async flush() {
-      // Simple client doesn't need explicit flushing
-      return Promise.resolve();
+      // Call the /flush endpoint to signal test completion and trigger summary output
+      try {
+        let {
+          status,
+          json
+        } = await httpPost(`${serverUrl}/flush`, {}, DEFAULT_TIMEOUT_MS);
+        if (status >= 200 && status < 300) {
+          return json;
+        }
+      } catch {
+        // Silently ignore flush errors - server may not be running
+      }
+      return null;
     }
   };
 }
@@ -240,13 +310,10 @@ export async function vizzlyScreenshot(name, imageBuffer, options = {}) {
   if (isVizzlyDisabled()) {
     return; // Silently skip when disabled
   }
-  const client = getClient();
+  let client = getClient();
   if (!client) {
-    if (!hasLoggedWarning) {
-      console.warn('Vizzly client not initialized. Screenshots will be skipped.');
-      hasLoggedWarning = true;
-      disableVizzly();
-    }
+    // Silently disable - no server running, nothing to do
+    disableVizzly();
     return;
   }