@vizzly-testing/cli 0.30.0 → 0.31.0

package/dist/commands/doctor.js

@@ -1,23 +1,12 @@
 import { URL } from 'node:url';
-import { createApiClient, getBuilds } from '../api/index.js';
-import { ConfigError } from '../errors/vizzly-error.js';
-import { loadConfig } from '../utils/config-loader.js';
-import { getContext } from '../utils/context.js';
-import { getApiToken } from '../utils/environment-config.js';
-import * as output from '../utils/output.js';
-
-/**
- * Doctor command implementation - Run diagnostics to check environment
- * @param {Object} options - Command options
- * @param {Object} globalOptions - Global CLI options
- */
-export async function doctorCommand(options = {}, globalOptions = {}) {
-  output.configure({
-    json: globalOptions.json,
-    verbose: globalOptions.verbose,
-    color: !globalOptions.noColor
-  });
-  let diagnostics = {
+import { createApiClient as defaultCreateApiClient, getBuilds as defaultGetBuilds } from '../api/index.js';
+import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
+import { getContext as defaultGetContext } from '../utils/context.js';
+import { getApiToken as defaultGetApiToken } from '../utils/environment-config.js';
+import * as defaultOutput from '../utils/output.js';
+export let MIN_NODE_MAJOR = 22;
+export function createDoctorDiagnostics() {
+  return {
     environment: {
       nodeVersion: null,
       nodeVersionValid: null
@@ -35,79 +24,126 @@ export async function doctorCommand(options = {}, globalOptions = {}) {
       error: null
     }
   };
+}
+export function getNodeVersionCheck(nodeVersion = process.version, minMajor = MIN_NODE_MAJOR) {
+  let nodeMajor = parseNodeMajorVersion(nodeVersion);
+  let ok = nodeMajor !== null && nodeMajor >= minMajor;
+  let value = ok ? `${nodeVersion} (supported)` : nodeMajor === null ? `${nodeVersion} (unrecognized Node.js version)` : `${nodeVersion} (requires >= ${minMajor})`;
+  return {
+    diagnostic: {
+      nodeVersion,
+      nodeVersionValid: ok
+    },
+    check: {
+      name: 'Node.js',
+      value,
+      ok
+    }
+  };
+}
+function parseNodeMajorVersion(nodeVersion) {
+  let match = /^v?(\d+)\.\d+\.\d+$/.exec(nodeVersion);
+  return match ? Number(match[1]) : null;
+}
+export function getApiUrlCheck(apiUrl) {
+  try {
+    let url = new URL(apiUrl);
+    if (!['http:', 'https:'].includes(url.protocol)) {
+      throw new Error('URL must use http or https');
+    }
+    return {
+      apiUrl,
+      apiUrlValid: true,
+      check: {
+        name: 'API URL',
+        value: apiUrl,
+        ok: true
+      }
+    };
+  } catch {
+    return {
+      apiUrl,
+      apiUrlValid: false,
+      check: {
+        name: 'API URL',
+        value: 'invalid (check VIZZLY_API_URL)',
+        ok: false
+      }
+    };
+  }
+}
+export function getThresholdCheck(thresholdValue) {
+  let threshold = Number(thresholdValue);
+  // CIEDE2000 threshold: 0 = exact, 1 = JND, 2 = recommended, 3+ = permissive
+  let thresholdValid = Number.isFinite(threshold) && threshold >= 0;
+  return {
+    threshold,
+    thresholdValid,
+    check: thresholdValid ? {
+      name: 'Threshold',
+      value: `${threshold} (CIEDE2000)`,
+      ok: true
+    } : {
+      name: 'Threshold',
+      value: 'invalid',
+      ok: false
+    }
+  };
+}
+
+/**
+ * Doctor command implementation - Run diagnostics to check environment
+ * @param {Object} options - Command options
+ * @param {Object} globalOptions - Global CLI options
+ * @param {Object} deps - Dependencies for testing
+ */
+export async function doctorCommand(options = {}, globalOptions = {}, deps = {}) {
+  let {
+    createApiClient = defaultCreateApiClient,
+    getApiToken = defaultGetApiToken,
+    getBuilds = defaultGetBuilds,
+    getContext = defaultGetContext,
+    loadConfig = defaultLoadConfig,
+    nodeVersion = process.version,
+    output = defaultOutput,
+    exit = code => process.exit(code)
+  } = deps;
+  output.configure({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  let diagnostics = createDoctorDiagnostics();
   let hasErrors = false;
   let checks = [];
   try {
     // Determine if we'll attempt remote checks (API connectivity)
-    let willCheckConnectivity = Boolean(options.api || getApiToken());
+    let hasApiToken = Boolean(getApiToken());
+    let willCheckConnectivity = Boolean(options.api || hasApiToken);
 
     // Show header
     output.header('doctor', willCheckConnectivity ? 'full' : 'local');
-
-    // Node.js version check (require >= 20)
-    let nodeVersion = process.version;
-    let nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0], 10);
-    diagnostics.environment.nodeVersion = nodeVersion;
-    diagnostics.environment.nodeVersionValid = nodeMajor >= 20;
-    if (nodeMajor >= 20) {
-      checks.push({
-        name: 'Node.js',
-        value: `${nodeVersion} (supported)`,
-        ok: true
-      });
-    } else {
-      checks.push({
-        name: 'Node.js',
-        value: `${nodeVersion} (requires >= 20)`,
-        ok: false
-      });
+    let nodeCheck = getNodeVersionCheck(nodeVersion);
+    diagnostics.environment = nodeCheck.diagnostic;
+    checks.push(nodeCheck.check);
+    if (!nodeCheck.check.ok) {
       hasErrors = true;
     }
 
     // Load configuration (apply global CLI overrides like --config only)
     let config = await loadConfig(globalOptions.config);
-
-    // Validate apiUrl
-    diagnostics.configuration.apiUrl = config.apiUrl;
-    try {
-      let url = new URL(config.apiUrl);
-      if (!['http:', 'https:'].includes(url.protocol)) {
-        throw new ConfigError('URL must use http or https');
-      }
-      diagnostics.configuration.apiUrlValid = true;
-      checks.push({
-        name: 'API URL',
-        value: config.apiUrl,
-        ok: true
-      });
-    } catch (_e) {
-      diagnostics.configuration.apiUrlValid = false;
-      checks.push({
-        name: 'API URL',
-        value: 'invalid (check VIZZLY_API_URL)',
-        ok: false
-      });
+    let apiUrlCheck = getApiUrlCheck(config.apiUrl);
+    diagnostics.configuration.apiUrl = apiUrlCheck.apiUrl;
+    diagnostics.configuration.apiUrlValid = apiUrlCheck.apiUrlValid;
+    checks.push(apiUrlCheck.check);
+    if (!apiUrlCheck.check.ok) {
       hasErrors = true;
     }
-
-    // Validate threshold (0..1 inclusive)
-    let threshold = Number(config?.comparison?.threshold);
-    diagnostics.configuration.threshold = threshold;
-    // CIEDE2000 threshold: 0 = exact, 1 = JND, 2 = recommended, 3+ = permissive
-    let thresholdValid = Number.isFinite(threshold) && threshold >= 0;
-    diagnostics.configuration.thresholdValid = thresholdValid;
-    if (thresholdValid) {
-      checks.push({
-        name: 'Threshold',
-        value: `${threshold} (CIEDE2000)`,
-        ok: true
-      });
-    } else {
-      checks.push({
-        name: 'Threshold',
-        value: 'invalid',
-        ok: false
-      });
+    let thresholdCheck = getThresholdCheck(config?.comparison?.threshold);
+    diagnostics.configuration.threshold = thresholdCheck.threshold;
+    diagnostics.configuration.thresholdValid = thresholdCheck.thresholdValid;
+    checks.push(thresholdCheck.check);
+    if (!thresholdCheck.check.ok) {
       hasErrors = true;
     }
 
@@ -121,8 +157,7 @@ export async function doctorCommand(options = {}, globalOptions = {}) {
     });
 
     // Optional: API connectivity check when --api is provided or VIZZLY_TOKEN is present
-    let autoApi = Boolean(getApiToken());
-    if (options.api || autoApi) {
+    if (willCheckConnectivity) {
       diagnostics.connectivity.checked = true;
       if (!config.apiKey) {
         diagnostics.connectivity.ok = false;
@@ -227,7 +262,7 @@ export async function doctorCommand(options = {}, globalOptions = {}) {
     output.error('Failed to run preflight', error);
   } finally {
     output.cleanup();
-    if (hasErrors) process.exit(1);
+    if (hasErrors) exit(1);
   }
 }
 

package/dist/commands/init.js

@@ -6,79 +6,111 @@ import { VizzlyError } from '../errors/vizzly-error.js';
 import { loadPlugins } from '../plugin-loader.js';
 import { loadConfig } from '../utils/config-loader.js';
 import * as output from '../utils/output.js';
-
-/**
- * Simple configuration setup for Vizzly CLI
- */
-export class InitCommand {
-  constructor(plugins = []) {
-    this.plugins = plugins;
+let configValueSchema = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(configValueSchema), z.record(z.string(), configValueSchema)]));
+let configSchemaValidator = z.record(z.string(), configValueSchema);
+function createInitDeps(deps = {}) {
+  return {
+    access: deps.access || fs.access,
+    cwd: deps.cwd || (() => process.cwd()),
+    loadConfig: deps.loadConfig || loadConfig,
+    loadPlugins: deps.loadPlugins || loadPlugins,
+    output: deps.output || output,
+    writeFile: deps.writeFile || fs.writeFile
+  };
+}
+function configureOutput(output, options) {
+  output.configure({
+    json: options.json || false,
+    verbose: options.verbose || false,
+    color: options.color !== false
+  });
+}
+export function getInitConfigPath(cwd = process.cwd()) {
+  return path.join(cwd, 'vizzly.config.js');
+}
+export async function fileExists(filePath, access = fs.access) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
   }
-  async run(options = {}) {
-    // Check for existing config
-    let configPath = path.join(process.cwd(), 'vizzly.config.js');
-    let hasConfig = await this.fileExists(configPath);
-    if (hasConfig && !options.force) {
-      // JSON output for skipped
-      if (options.json) {
-        output.data({
-          status: 'skipped',
-          reason: 'config_exists',
-          configPath,
-          message: 'A vizzly.config.js file already exists. Use --force to overwrite.'
-        });
-        return {
-          status: 'skipped',
-          configPath
-        };
-      }
-      output.header('init');
-      output.warn('A vizzly.config.js file already exists');
-      output.hint('Use --force to overwrite');
-      return {
-        status: 'skipped',
-        configPath
-      };
+}
+export function getPluginsWithConfig(plugins = []) {
+  return plugins.filter(plugin => plugin.configSchema);
+}
+export function getPluginConfigNames(plugins = []) {
+  return getPluginsWithConfig(plugins).map(plugin => plugin.name);
+}
+function formatObjectKey(key) {
+  if (/^[A-Za-z_$][\w$]*$/.test(key)) {
+    return key;
+  }
+  return formatValue(key);
+}
+export function formatValue(value, depth = 0) {
+  let indent = '  '.repeat(depth);
+  let nextIndent = '  '.repeat(depth + 1);
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (typeof value === 'string') {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n')}'`;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    let items = value.map(item => {
+      let formatted = formatValue(item, depth + 1);
+      return `${nextIndent}${formatted}`;
+    });
+    return `[\n${items.join(',\n')}\n${indent}]`;
+  }
+  if (typeof value === 'object') {
+    let entries = Object.entries(value);
+    if (entries.length === 0) return '{}';
+    let props = entries.map(([key, entryValue]) => {
+      let formatted = formatValue(entryValue, depth + 1);
+      return `${nextIndent}${formatObjectKey(key)}: ${formatted}`;
+    });
+    return `{\n${props.join(',\n')}\n${indent}}`;
+  }
+  return String(value);
+}
+export function formatPluginConfig(plugin, output = null) {
+  try {
+    configSchemaValidator.parse(plugin.configSchema);
+    let configEntries = [];
+    for (let [key, value] of Object.entries(plugin.configSchema)) {
+      let formattedValue = formatValue(value, 1);
+      configEntries.push(`  // ${plugin.name} plugin configuration\n  ${formatObjectKey(key)}: ${formattedValue}`);
     }
-    try {
-      // Generate config file with defaults
-      await this.generateConfigFile(configPath, options);
-
-      // Get plugins with config for JSON output
-      let pluginsWithConfig = this.plugins.filter(p => p.configSchema);
-      let pluginNames = pluginsWithConfig.map(p => p.name);
-
-      // JSON output for success
-      if (options.json) {
-        output.data({
-          status: 'created',
-          configPath,
-          plugins: pluginNames
-        });
-        return {
-          status: 'created',
-          configPath,
-          plugins: pluginNames
-        };
+    return configEntries.join(',\n\n');
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      let messages = error.issues.map(zodError => `${zodError.path.join('.')}: ${zodError.message}`);
+      output?.warn(`Invalid config schema for plugin ${plugin.name}: ${messages.join(', ')}`);
+    } else {
+      output?.warn(`Failed to format config for plugin ${plugin.name}: ${error.message}`);
+    }
+    return '';
+  }
+}
+export function generatePluginConfigs(plugins = [], output = null) {
+  let sections = [];
+  for (let plugin of plugins) {
+    if (plugin.configSchema) {
+      let configStr = formatPluginConfig(plugin, output);
+      if (configStr) {
+        sections.push(configStr);
       }
-
-      // Show next steps
-      this.showNextSteps();
-      output.blank();
-      output.complete('Vizzly CLI setup complete');
-      return {
-        status: 'created',
-        configPath,
-        plugins: pluginNames
-      };
-    } catch (error) {
-      throw new VizzlyError('Failed to initialize Vizzly configuration', 'INIT_FAILED', {
-        error: error.message
-      });
     }
   }
-  async generateConfigFile(configPath, options = {}) {
-    let coreConfig = `export default {
+  return sections.length > 0 ? sections.join(',\n\n') : '';
+}
+export function createConfigContent(plugins = [], output = null) {
+  let coreConfig = `export default {
   // Server configuration (for run command)
   server: {
     port: 47392,
@@ -100,155 +132,124 @@ export class InitCommand {
 
   // Comparison configuration (CIEDE2000 Delta E: 0=exact, 1=JND, 2=recommended)
   comparison: {
-    threshold: 2.0
+    threshold: 2.0,
+    minClusterSize: 2
   },
 
   // TDD configuration
   tdd: {
     openReport: false // Whether to auto-open HTML report in browser
   }`;
-
-    // Add plugin configurations
-    const pluginConfigs = this.generatePluginConfigs();
-    if (pluginConfigs) {
-      coreConfig += `,\n\n${pluginConfigs}`;
-    }
-    coreConfig += '\n};\n';
-    await fs.writeFile(configPath, coreConfig, 'utf8');
-
-    // Skip human-readable output in JSON mode
-    if (options.json) return;
-    output.header('init');
-    output.complete('Created vizzly.config.js');
-
-    // Log discovered plugins
-    let pluginsWithConfig = this.plugins.filter(p => p.configSchema);
-    if (pluginsWithConfig.length > 0) {
-      output.hint(`Added config for ${pluginsWithConfig.length} plugin(s):`);
-      output.list(pluginsWithConfig.map(p => p.name), {
-        indent: 4
-      });
-    }
+  let pluginConfigs = generatePluginConfigs(plugins, output);
+  if (pluginConfigs) {
+    coreConfig += `,\n\n${pluginConfigs}`;
   }
-
-  /**
-   * Generate configuration sections for plugins
-   * @returns {string} Plugin config sections as formatted string
-   */
-  generatePluginConfigs() {
-    const sections = [];
-    for (const plugin of this.plugins) {
-      if (plugin.configSchema) {
-        const configStr = this.formatPluginConfig(plugin);
-        if (configStr) {
-          sections.push(configStr);
-        }
-      }
-    }
-    return sections.length > 0 ? sections.join(',\n\n') : '';
-  }
-
-  /**
-   * Format a plugin's config schema as JavaScript code
-   * @param {Object} plugin - Plugin with configSchema
-   * @returns {string} Formatted config string
-   */
-  formatPluginConfig(plugin) {
-    try {
-      // Validate config schema structure with Zod (defensive check)
-      const configValueSchema = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(configValueSchema), z.record(configValueSchema)]));
-      const configSchemaValidator = z.record(configValueSchema);
-      configSchemaValidator.parse(plugin.configSchema);
-      const configEntries = [];
-      for (const [key, value] of Object.entries(plugin.configSchema)) {
-        const formattedValue = this.formatValue(value, 1);
-        configEntries.push(`  // ${plugin.name} plugin configuration\n  ${key}: ${formattedValue}`);
-      }
-      return configEntries.join(',\n\n');
-    } catch (error) {
-      if (error instanceof z.ZodError) {
-        const messages = error.errors.map(e => `${e.path.join('.')}: ${e.message}`);
-        output.warn(`Invalid config schema for plugin ${plugin.name}: ${messages.join(', ')}`);
-      } else {
-        output.warn(`Failed to format config for plugin ${plugin.name}: ${error.message}`);
-      }
-      return '';
-    }
+  return `${coreConfig}\n};\n`;
+}
+function writeHumanCreatedOutput(output, plugins) {
+  output.header('init');
+  output.complete('Created vizzly.config.js');
+  let pluginsWithConfig = getPluginsWithConfig(plugins);
+  if (pluginsWithConfig.length > 0) {
+    output.hint(`Added config for ${pluginsWithConfig.length} plugin(s):`);
+    output.list(pluginsWithConfig.map(plugin => plugin.name), {
+      indent: 4
+    });
   }
-
-  /**
-   * Format a JavaScript value with proper indentation
-   * @param {*} value - Value to format
-   * @param {number} depth - Current indentation depth
-   * @returns {string} Formatted value
-   */
-  formatValue(value, depth = 0) {
-    const indent = '  '.repeat(depth);
-    const nextIndent = '  '.repeat(depth + 1);
-    if (value === null) return 'null';
-    if (value === undefined) return 'undefined';
-    if (typeof value === 'string') return `'${value.replace(/'/g, "\\'")}'`;
-    if (typeof value === 'number' || typeof value === 'boolean') return String(value);
-    if (Array.isArray(value)) {
-      if (value.length === 0) return '[]';
-      const items = value.map(item => {
-        const formatted = this.formatValue(item, depth + 1);
-        return `${nextIndent}${formatted}`;
-      });
-      return `[\n${items.join(',\n')}\n${indent}]`;
-    }
-    if (typeof value === 'object') {
-      const entries = Object.entries(value);
-      if (entries.length === 0) return '{}';
-      const props = entries.map(([k, v]) => {
-        const formatted = this.formatValue(v, depth + 1);
-        return `${nextIndent}${k}: ${formatted}`;
-      });
-      return `{\n${props.join(',\n')}\n${indent}}`;
-    }
-    return String(value);
+}
+function showNextSteps(output) {
+  output.blank();
+  output.labelValue('Next steps', '');
+  output.list(['Set your API token: export VIZZLY_TOKEN="your-api-key"', 'Run your tests with Vizzly: npx vizzly run "npm test"', 'Upload screenshots: npx vizzly upload ./screenshots']);
+}
+async function writeConfigFile({
+  configPath,
+  plugins,
+  options,
+  output,
+  writeFile
+}) {
+  let coreConfig = createConfigContent(plugins, output);
+  await writeFile(configPath, coreConfig, 'utf8');
+  if (!options.json) {
+    writeHumanCreatedOutput(output, plugins);
   }
-  showNextSteps() {
-    output.blank();
-    output.labelValue('Next steps', '');
-    output.list(['Set your API token: export VIZZLY_TOKEN="your-api-key"', 'Run your tests with Vizzly: npx vizzly run "npm test"', 'Upload screenshots: npx vizzly upload ./screenshots']);
+}
+async function loadInitPlugins(options, deps) {
+  if (options.plugins) {
+    return options.plugins;
   }
-  async fileExists(filePath) {
-    try {
-      await fs.access(filePath);
-      return true;
-    } catch {
-      return false;
-    }
+  try {
+    let config = await deps.loadConfig(options.config, {});
+    return await deps.loadPlugins(options.config, config, null);
+  } catch {
+    return [];
   }
 }
 
 // Export factory function for CLI
 export function createInitCommand(options) {
-  const command = new InitCommand(options.plugins);
-  return () => command.run(options);
+  return () => init(options);
 }
-
-// Simple export for direct CLI usage
-export async function init(options = {}) {
-  output.configure({
-    json: options.json || false,
-    verbose: options.verbose || false,
-    color: options.color !== false
-  });
-  let plugins = [];
-
-  // Try to load plugins if not provided
-  if (!options.plugins) {
-    try {
-      const config = await loadConfig(options.config, {});
-      plugins = await loadPlugins(options.config, config, null);
-    } catch {
-      // Silent fail - plugins are optional for init
+export async function init(options = {}, deps = {}) {
+  let resolvedDeps = createInitDeps(deps);
+  configureOutput(resolvedDeps.output, options);
+  let plugins = await loadInitPlugins(options, resolvedDeps);
+  let configPath = getInitConfigPath(resolvedDeps.cwd());
+  let hasConfig = await fileExists(configPath, resolvedDeps.access);
+  if (hasConfig && !options.force) {
+    if (options.json) {
+      resolvedDeps.output.data({
+        status: 'skipped',
+        reason: 'config_exists',
+        configPath,
+        message: 'A vizzly.config.js file already exists. Use --force to overwrite.'
+      });
+      return {
+        status: 'skipped',
+        configPath
+      };
+    }
+    resolvedDeps.output.header('init');
+    resolvedDeps.output.warn('A vizzly.config.js file already exists');
+    resolvedDeps.output.hint('Use --force to overwrite');
+    return {
+      status: 'skipped',
+      configPath
+    };
+  }
+  try {
+    await writeConfigFile({
+      configPath,
+      plugins,
+      options,
+      output: resolvedDeps.output,
+      writeFile: resolvedDeps.writeFile
+    });
+    let pluginNames = getPluginConfigNames(plugins);
+    if (options.json) {
+      resolvedDeps.output.data({
+        status: 'created',
+        configPath,
+        plugins: pluginNames
+      });
+      return {
+        status: 'created',
+        configPath,
+        plugins: pluginNames
+      };
     }
-  } else {
-    plugins = options.plugins;
+    showNextSteps(resolvedDeps.output);
+    resolvedDeps.output.blank();
+    resolvedDeps.output.complete('Vizzly CLI setup complete');
+    return {
+      status: 'created',
+      configPath,
+      plugins: pluginNames
+    };
+  } catch (error) {
+    throw new VizzlyError('Failed to initialize Vizzly configuration', 'INIT_FAILED', {
+      error: error.message
+    });
   }
-  const command = new InitCommand(plugins);
-  return await command.run(options);
 }