@vizzly-testing/cli 0.29.6 → 0.31.0

package/dist/cli.js

@@ -6,6 +6,7 @@ import { baselinesCommand, validateBaselinesOptions } from './commands/baselines
 import { buildsCommand, validateBuildsOptions } from './commands/builds.js';
 import { comparisonsCommand, validateComparisonsOptions } from './commands/comparisons.js';
 import { configCommand, validateConfigOptions } from './commands/config-cmd.js';
+import { contextBuildCommand, contextComparisonCommand, contextReviewQueueCommand, contextScreenshotCommand, contextSimilarCommand, validateContextBuildOptions, validateContextComparisonOptions, validateContextReviewQueueOptions, validateContextScreenshotOptions, validateContextSimilarOptions } from './commands/context.js';
 import { doctorCommand, validateDoctorOptions } from './commands/doctor.js';
 import { finalizeCommand, validateFinalizeOptions } from './commands/finalize.js';
 import { init } from './commands/init.js';
@@ -13,18 +14,20 @@ import { loginCommand, validateLoginOptions } from './commands/login.js';
 import { logoutCommand, validateLogoutOptions } from './commands/logout.js';
 import { orgsCommand, validateOrgsOptions } from './commands/orgs.js';
 import { previewCommand, validatePreviewOptions } from './commands/preview.js';
+import { projectLinkCommand, validateProjectLinkOptions } from './commands/project.js';
 import { projectsCommand, validateProjectsOptions } from './commands/projects.js';
 import { approveCommand, commentCommand, rejectCommand, validateApproveOptions, validateCommentOptions, validateRejectOptions } from './commands/review.js';
 import { runCommand, validateRunOptions } from './commands/run.js';
 import { statusCommand, validateStatusOptions } from './commands/status.js';
 import { tddCommand, validateTddOptions } from './commands/tdd.js';
-import { runDaemonChild, tddListCommand, tddStartCommand, tddStatusCommand, tddStopCommand } from './commands/tdd-daemon.js';
+import { runDaemonChild, tddListCommand, tddStartCommand, tddStatusCommand, tddStopCommand, validateTddStartOptions } from './commands/tdd-daemon.js';
 import { uploadCommand, validateUploadOptions } from './commands/upload.js';
 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 { generateStaticReport, getReportFileUrl } from './services/static-report-generator.js';
+import { withTimeout } from './utils/async-utils.js';
 import { openBrowser } from './utils/browser.js';
 import { colors } from './utils/colors.js';
 import { loadConfig } from './utils/config-loader.js';
@@ -46,7 +49,7 @@ const formatHelp = (cmd, helper) => {
     // 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')}`);
+    lines.push(`   ${c.gray('Visual review for agents and teams')}`);
   } else {
     // Compact header for subcommands
     lines.push(`  ${c.brand.amber(c.bold('vizzly'))} ${c.white(cmd.name())}`);
@@ -71,7 +74,7 @@ const formatHelp = (cmd, helper) => {
         key: 'core',
         icon: '▸',
         title: 'Core',
-        names: ['run', 'tdd', 'upload', 'status', 'finalize', 'preview', 'builds', 'comparisons']
+        names: ['run', 'tdd', 'upload', 'status', 'context', 'finalize', 'preview', 'builds', 'comparisons']
       }, {
         key: 'review',
         icon: '▸',
@@ -170,7 +173,7 @@ const formatHelp = (cmd, helper) => {
   if (isRootCommand) {
     lines.push(`  ${c.brand.amber('▸')} ${c.bold('Quick Start')}`);
     lines.push('');
-    lines.push(`      ${c.dim('# Local visual testing')}`);
+    lines.push(`      ${c.dim('# Local visual review')}`);
     lines.push(`      ${c.gray('$')} ${c.white('vizzly tdd start')}`);
     lines.push('');
     lines.push(`      ${c.dim('# CI pipeline')}`);
@@ -202,40 +205,65 @@ const formatHelp = (cmd, helper) => {
   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 [fields]', 'JSON output, optionally specify fields (e.g., --json id,status,branch)').option('--color', 'Force colored output (even in non-TTY)').option('--no-color', 'Disable colored output').option('--strict', 'Fail on any error (default: be resilient, warn on non-critical issues)').configureHelp({
+function extractGlobalOptionsFromArgv(argv, commandNames = null) {
+  let configPath = null;
+  let verboseMode = false;
+  let logLevelArg = null;
+  let jsonArg = null;
+  for (let i = 0; i < argv.length; i++) {
+    if ((argv[i] === '-c' || argv[i] === '--config') && argv[i + 1]) {
+      configPath = argv[i + 1];
+    }
+    if (argv[i] === '-v' || argv[i] === '--verbose') {
+      verboseMode = true;
+    }
+    if (argv[i] === '--log-level' && argv[i + 1]) {
+      logLevelArg = argv[i + 1];
+    }
+    if (argv[i] === '--json') {
+      let nextArg = argv[i + 1];
+      let nextArgIsCommand = commandNames?.has(nextArg);
+      if (nextArg && !nextArg.startsWith('-') && !nextArgIsCommand) {
+        jsonArg = nextArg;
+      } else {
+        jsonArg = true;
+      }
+    } else if (argv[i].startsWith('--json=')) {
+      jsonArg = argv[i].substring('--json='.length);
+    }
+  }
+  return {
+    configPath,
+    verboseMode,
+    logLevelArg,
+    jsonArg
+  };
+}
+function normalizeJsonArgv(argv, commandNames) {
+  let normalizedArgv = [...argv];
+  for (let i = 0; i < normalizedArgv.length; i++) {
+    if (normalizedArgv[i] !== '--json') {
+      continue;
+    }
+    let nextArg = normalizedArgv[i + 1];
+    if (nextArg && !nextArg.startsWith('-') && commandNames.has(nextArg)) {
+      normalizedArgv[i] = '--json=true';
+    }
+  }
+  return normalizedArgv;
+}
+program.name('vizzly').description('Vizzly CLI for visual review').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 [fields]', 'JSON output, optionally specify fields (e.g., --json id,status,branch)').option('--color', 'Force colored output (even in non-TTY)').option('--no-color', 'Disable colored output').option('--strict', 'Fail on any error (default: be resilient, warn on non-critical issues)').configureHelp({
   formatHelp
 });
 
 // Load plugins before defining commands
 // We need to manually parse to get the config option early
-let configPath = null;
-let verboseMode = false;
-let logLevelArg = null;
-let jsonArg = null;
-for (let i = 0; i < process.argv.length; i++) {
-  if ((process.argv[i] === '-c' || process.argv[i] === '--config') && process.argv[i + 1]) {
-    configPath = process.argv[i + 1];
-  }
-  if (process.argv[i] === '-v' || process.argv[i] === '--verbose') {
-    verboseMode = true;
-  }
-  if (process.argv[i] === '--log-level' && process.argv[i + 1]) {
-    logLevelArg = process.argv[i + 1];
-  }
-  // Handle --json with optional field selection
-  // --json (no value) = true, --json=fields or --json fields = "fields"
-  if (process.argv[i] === '--json') {
-    let nextArg = process.argv[i + 1];
-    // If next arg exists and doesn't start with -, it's the fields value
-    if (nextArg && !nextArg.startsWith('-')) {
-      jsonArg = nextArg;
-    } else {
-      jsonArg = true;
-    }
-  } else if (process.argv[i].startsWith('--json=')) {
-    jsonArg = process.argv[i].substring('--json='.length);
-  }
-}
+let {
+  configPath,
+  verboseMode,
+  logLevelArg,
+  jsonArg
+} = extractGlobalOptionsFromArgv(process.argv);
 
 // Configure output early
 // Priority: --log-level > --verbose > VIZZLY_LOG_LEVEL env var > default ('info')
@@ -258,18 +286,15 @@ const pluginServices = createPluginServices(services);
 let plugins = [];
 try {
   plugins = await loadPlugins(configPath, config);
-  for (const plugin of plugins) {
+  for (let plugin of plugins) {
     try {
       // Add timeout protection for plugin registration (5 seconds)
-      const registerPromise = plugin.register(program, {
+      let registerPromise = plugin.register(program, {
         config,
         services: pluginServices,
-        output,
-        // Backwards compatibility alias for plugins using old API
-        logger: output
+        output
       });
-      const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Plugin registration timeout (5s)')), 5000));
-      await Promise.race([registerPromise, timeoutPromise]);
+      await withTimeout(registerPromise, 5000, 'Plugin registration timeout (5s)');
       output.debug(`Registered plugin: ${plugin.name}`);
     } catch (error) {
       output.warn(`Failed to register plugin ${plugin.name}: ${error.message}`);
@@ -286,7 +311,7 @@ program.command('init').description('Initialize Vizzly in your project').option(
     plugins
   });
 });
-program.command('upload').description('Upload screenshots to Vizzly').argument('<path>', 'Path to screenshots directory or file').option('-b, --build-name <name>', 'Build name for grouping').option('-m, --metadata <json>', 'Additional metadata as JSON').option('--batch-size <n>', 'Upload batch size', v => parseInt(v, 10)).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', v => parseInt(v, 10)).option('--branch <branch>', 'Git branch').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (path, options) => {
+program.command('upload').description('Upload screenshots to Vizzly').argument('<path>', 'Path to screenshots directory or file').option('-b, --build-name <name>', 'Build name for grouping').option('-m, --metadata <json>', 'Additional metadata as JSON').option('--batch-size <n>', 'Upload batch size', Number).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', Number).option('--branch <branch>', 'Git branch').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (path, options) => {
   const globalOptions = program.opts();
 
   // Validate options
@@ -301,11 +326,11 @@ program.command('upload').description('Upload screenshots to Vizzly').argument('
   await uploadCommand(path, options, globalOptions);
 });
 
-// TDD command with subcommands - Local visual testing with interactive dashboard
-const tddCmd = program.command('tdd').description('Run tests in TDD mode with local visual comparisons');
+// TDD command with subcommands - local visual review with an interactive dashboard
+const tddCmd = program.command('tdd').description('Run tests in TDD mode with local visual review');
 
 // TDD Start - Background server
-tddCmd.command('start').description('Start background TDD server with dashboard').option('--port <port>', 'Port for TDD server', '47392').option('--open', 'Open dashboard in browser').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--token <token>', 'API token override').option('--daemon-child', 'Internal: run as daemon child process').action(async options => {
+tddCmd.command('start').description('Start background TDD server with dashboard').option('--port <port>', 'Port for TDD server', '47392').option('--open', 'Open dashboard in browser').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--token <token>', 'API token override').option('--daemon-child', 'Internal: run as daemon child process').action(async options => {
   const globalOptions = program.opts();
 
   // If this is a daemon child process, run the server directly
@@ -313,6 +338,14 @@ tddCmd.command('start').description('Start background TDD server with dashboard'
     await runDaemonChild(options, globalOptions);
     return;
   }
+  let validationErrors = validateTddStartOptions(options);
+  if (validationErrors.length > 0) {
+    output.error('Validation errors:');
+    for (let error of validationErrors) {
+      output.printErr(`  - ${error}`);
+    }
+    process.exit(1);
+  }
   await tddStartCommand(options, globalOptions);
 });
 
@@ -335,7 +368,7 @@ tddCmd.command('list').description('List all running TDD servers').action(async
 });
 
 // TDD Run - One-off test run with ephemeral server (generates static report)
-tddCmd.command('run <command>').description('Run tests once in TDD mode with local visual comparisons').option('--port <port>', 'Port for TDD server', '47392').option('--branch <branch>', 'Git branch override').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', parseFloat).option('--token <token>', 'API token override').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--set-baseline', 'Accept current screenshots as new baseline (overwrites existing)').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--no-open', 'Skip opening report in browser').action(async (command, options) => {
+tddCmd.command('run <command>').description('Run tests once in TDD mode with local visual review').option('--port <port>', 'Port for TDD server', '47392').option('--branch <branch>', 'Git branch override').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--token <token>', 'API token override').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--set-baseline', 'Accept current screenshots as new baseline (overwrites existing)').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--no-open', 'Skip opening report in browser').action(async (command, options) => {
   const globalOptions = program.opts();
 
   // Validate options
@@ -396,7 +429,7 @@ tddCmd.command('run <command>').description('Run tests once in TDD mode with loc
   await handleCleanup();
   process.exit(result?.exitCode || 0);
 });
-program.command('run').description('Run tests with Vizzly integration').argument('<command>', 'Test command to run').option('--port <port>', 'Port for screenshot server', '47392').option('-b, --build-name <name>', 'Custom build name').option('--branch <branch>', 'Git branch override').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--allow-no-token', 'Allow running without API token').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (command, options) => {
+program.command('run').description('Run tests with Vizzly integration').argument('<command>', 'Test command to run').option('--port <port>', 'Port for screenshot server', '47392').option('-b, --build-name <name>', 'Custom build name').option('--branch <branch>', 'Git branch override').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--batch-size <n>', 'Upload batch size', Number).option('--upload-timeout <ms>', 'Upload timeout in milliseconds', Number).option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--allow-no-token', 'Allow running without API token').option('--upload-all', 'Upload all screenshots without SHA deduplication').option('--parallel-id <id>', 'Unique identifier for parallel test execution').action(async (command, options) => {
   const globalOptions = program.opts();
 
   // Validate options
@@ -432,7 +465,7 @@ program.command('status').description('Check the status of a build').argument('<
   }
   await statusCommand(buildId, options, globalOptions);
 });
-program.command('builds').description('List and query builds').option('-b, --build <id>', 'Get a specific build by ID').option('--branch <branch>', 'Filter by branch').option('--status <status>', 'Filter by status (created, pending, processing, completed, failed)').option('--environment <env>', 'Filter by environment').option('-p, --project <slug>', 'Filter by project slug').option('--org <slug>', 'Filter by organization slug').option('--limit <n>', 'Maximum results to return (1-250)', val => parseInt(val, 10), 20).option('--offset <n>', 'Skip first N results', val => parseInt(val, 10), 0).option('--comparisons', 'Include comparisons when fetching a specific build').addHelpText('after', `
+program.command('builds').description('List and query builds').option('-b, --build <id>', 'Get a specific build by ID').option('--branch <branch>', 'Filter by branch').option('--status <status>', 'Filter by status (created, pending, processing, completed, failed)').option('--environment <env>', 'Filter by environment').option('-p, --project <slug>', 'Filter by project slug').option('--org <slug>', 'Filter by organization slug').option('--limit <n>', 'Maximum results to return (1-250)', Number, 20).option('--offset <n>', 'Skip first N results', Number, 0).option('--comparisons', 'Include comparisons when fetching a specific build').addHelpText('after', `
 Examples:
   $ vizzly builds                          # List recent builds
   $ vizzly builds --branch main            # Filter by branch
@@ -456,7 +489,7 @@ Examples:
   }
   await buildsCommand(options, globalOptions);
 });
-program.command('comparisons').description('Query and search comparisons').option('-b, --build <id>', 'Get comparisons for a specific build').option('--id <id>', 'Get a specific comparison by ID').option('--name <pattern>', 'Search comparisons by name (supports wildcards)').option('--status <status>', 'Filter by status (identical, new, changed)').option('--branch <branch>', 'Filter by branch (for name search)').option('--limit <n>', 'Maximum results to return (1-250)', val => parseInt(val, 10), 50).option('--offset <n>', 'Skip first N results', val => parseInt(val, 10), 0).option('-p, --project <slug>', 'Filter by project slug').option('--org <slug>', 'Filter by organization slug').addHelpText('after', `
+program.command('comparisons').description('Query and search comparisons').option('-b, --build <id>', 'Get comparisons for a specific build').option('--id <id>', 'Get a specific comparison by ID').option('--name <pattern>', 'Search comparisons by name (supports wildcards)').option('--status <status>', 'Filter by status (identical, new, changed)').option('--branch <branch>', 'Filter by branch (for name search)').option('--limit <n>', 'Maximum results to return (1-250)', Number, 50).option('--offset <n>', 'Skip first N results', Number, 0).option('-p, --project <slug>', 'Filter by project slug').option('--org <slug>', 'Filter by organization slug').addHelpText('after', `
 Examples:
   $ vizzly comparisons -b abc123           # List comparisons for a build
   $ vizzly comparisons --id def456         # Get specific comparison by ID
@@ -479,6 +512,98 @@ Examples:
   }
   await comparisonsCommand(options, globalOptions);
 });
+let contextCmd = program.command('context').description('Fetch build context for agents and reviewers');
+contextCmd.command('build').description('Fetch build context for agents and reviewers').argument('<build-id>', 'Build ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('--agent', 'Output compact context for LLM agents').option('--full', 'Return the full build context payload with --agent --json').option('--include <items>', 'Add detail to compact agent JSON: screenshots,diffs,comments').addHelpText('after', `
+Examples:
+  $ vizzly context build abc123
+  $ vizzly context build current --source local
+  $ vizzly context build current --source local --agent
+  $ vizzly context build abc123 --agent --json
+  $ vizzly context build abc123 --agent --json --include diffs,comments
+  $ vizzly context build abc123 --agent --json --full
+`).action(async (buildId, options) => {
+  const globalOptions = program.opts();
+  const validationErrors = validateContextBuildOptions(options);
+  if (validationErrors.length > 0) {
+    output.error('Validation errors:');
+    for (let error of validationErrors) {
+      output.printErr(`  - ${error}`);
+    }
+    process.exit(1);
+  }
+  await contextBuildCommand(buildId, options, globalOptions);
+});
+contextCmd.command('comparison').description('Fetch a comparison context bundle').argument('<comparison-id>', 'Comparison ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('--similar-limit <n>', 'Maximum similar fingerprint matches to return (1-50)', Number).option('--recent-limit <n>', 'Maximum recent same-name comparisons to return (1-50)', Number).option('--window-size <n>', 'Historical hotspot analysis window size (1-50)', Number).addHelpText('after', `
+Examples:
+  $ vizzly context comparison def456
+  $ vizzly context comparison def456 --source local
+  $ vizzly context comparison def456 --similar-limit 5 --recent-limit 5
+  $ vizzly context comparison def456 --json
+`).action(async (comparisonId, options) => {
+  const globalOptions = program.opts();
+  const validationErrors = validateContextComparisonOptions(options);
+  if (validationErrors.length > 0) {
+    output.error('Validation errors:');
+    for (let error of validationErrors) {
+      output.printErr(`  - ${error}`);
+    }
+    process.exit(1);
+  }
+  await contextComparisonCommand(comparisonId, options, globalOptions);
+});
+contextCmd.command('screenshot').description('Fetch screenshot context and historical memory').argument('<name>', 'Screenshot name').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--recent-limit <n>', 'Maximum recent comparisons to return (1-50)', Number).option('--window-size <n>', 'Historical hotspot analysis window size (1-50)', Number).addHelpText('after', `
+Examples:
+  $ vizzly context screenshot Dashboard
+  $ vizzly context screenshot Dashboard --source local
+  $ vizzly context screenshot Dashboard --project storybook --org acme
+  $ vizzly context screenshot Dashboard --json
+`).action(async (name, options) => {
+  const globalOptions = program.opts();
+  const validationErrors = validateContextScreenshotOptions(options);
+  if (validationErrors.length > 0) {
+    output.error('Validation errors:');
+    for (let error of validationErrors) {
+      output.printErr(`  - ${error}`);
+    }
+    process.exit(1);
+  }
+  await contextScreenshotCommand(name, options, globalOptions);
+});
+contextCmd.command('similar').description('Fetch project-scoped matches for a fingerprint hash').argument('<fingerprint-hash>', 'Fingerprint hash to search for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--limit <n>', 'Maximum matches to return (1-50)', Number).addHelpText('after', `
+Examples:
+  $ vizzly context similar fp-dashboard
+  $ vizzly context similar fp-dashboard --project storybook --org acme
+  $ vizzly context similar fp-dashboard --json
+`).action(async (fingerprintHash, options) => {
+  const globalOptions = program.opts();
+  const validationErrors = validateContextSimilarOptions(options);
+  if (validationErrors.length > 0) {
+    output.error('Validation errors:');
+    for (let error of validationErrors) {
+      output.printErr(`  - ${error}`);
+    }
+    process.exit(1);
+  }
+  await contextSimilarCommand(fingerprintHash, options, globalOptions);
+});
+contextCmd.command('review-queue').description('Fetch pending review context for a project').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--limit <n>', 'Maximum comparisons to return (1-100)', Number).option('--offset <n>', 'Skip first N comparisons', Number).addHelpText('after', `
+Examples:
+  $ vizzly context review-queue --project storybook --org acme
+  $ vizzly context review-queue --source local
+  $ vizzly context review-queue --limit 10
+  $ vizzly context review-queue --json
+`).action(async options => {
+  const globalOptions = program.opts();
+  const validationErrors = validateContextReviewQueueOptions(options);
+  if (validationErrors.length > 0) {
+    output.error('Validation errors:');
+    for (let error of validationErrors) {
+      output.printErr(`  - ${error}`);
+    }
+    process.exit(1);
+  }
+  await contextReviewQueueCommand(options, globalOptions);
+});
 program.command('config').description('Display current configuration').argument('[key]', 'Specific config key to get (dot notation, e.g., comparison.threshold)').action(async (key, options) => {
   const globalOptions = program.opts();
 
@@ -624,7 +749,7 @@ or the single organization for a project token.
   }
   await orgsCommand(options, globalOptions);
 });
-program.command('projects').description('List projects you have access to').option('--org <slug>', 'Filter by organization slug').option('--limit <n>', 'Maximum results to return (1-250)', val => parseInt(val, 10), 50).option('--offset <n>', 'Skip first N results', val => parseInt(val, 10), 0).addHelpText('after', `
+program.command('projects').description('List projects you have access to').option('--org <slug>', 'Filter by organization slug').option('--limit <n>', 'Maximum results to return (1-250)', Number, 50).option('--offset <n>', 'Skip first N results', Number, 0).addHelpText('after', `
 Examples:
   $ vizzly projects                        # List all projects
   $ vizzly projects --org my-company       # Filter by organization
@@ -646,6 +771,26 @@ Workflow:
   }
   await projectsCommand(options, globalOptions);
 });
+let projectCommand = program.command('project').description('Manage the project linked to this local checkout');
+projectCommand.command('link [selector]').description('Link a Vizzly project for cloud uploads').option('--org <slug>', 'Organization slug').option('--project <slug>', 'Project slug').option('--name <name>', 'Credential name shown in Vizzly').option('--expires-at <iso>', 'Optional token expiration timestamp').addHelpText('after', `
+Examples:
+  $ vizzly project link vizzly/storybook
+  $ vizzly project link --org vizzly --project storybook
+
+Note: run "vizzly login" first. The linked credential is project-scoped and is
+used for cloud uploads; your user login remains separate for review actions.
+`).action(async (selector, options) => {
+  const globalOptions = program.opts();
+  const validationErrors = validateProjectLinkOptions(selector, options);
+  if (validationErrors.length > 0) {
+    output.error('Validation errors:');
+    for (let error of validationErrors) {
+      output.printErr(`  - ${error}`);
+    }
+    process.exit(1);
+  }
+  await projectLinkCommand(selector, options, globalOptions);
+});
 program.command('finalize').description('Finalize a parallel build after all shards complete').argument('<parallel-id>', 'Parallel ID to finalize').action(async (parallelId, options) => {
   const globalOptions = program.opts();
 
@@ -660,7 +805,7 @@ program.command('finalize').description('Finalize a parallel build after all sha
   }
   await finalizeCommand(parallelId, options, globalOptions);
 });
-program.command('preview').description('Upload static files as a preview for a build').argument('[path]', 'Path to static files (dist/, build/, out/)').option('-b, --build <id>', 'Build ID to attach preview to').option('-p, --parallel-id <id>', 'Look up build by parallel ID').option('--base <path>', 'Override auto-detected base path').option('--open', 'Open preview URL in browser after upload').option('--dry-run', 'Show what would be uploaded without uploading').option('--public-link', 'Acknowledge that preview URL grants access to anyone with the link (required for private projects)').option('-x, --exclude <pattern>', 'Exclude files/dirs (repeatable, e.g. -x "*.log" -x "temp/")', (val, prev) => prev ? [...prev, val] : [val]).option('-i, --include <pattern>', 'Override default exclusions (repeatable, e.g. -i package.json -i tests/)', (val, prev) => prev ? [...prev, val] : [val]).action(async (path, options) => {
+program.command('preview').description('Upload static files as a preview for a build').argument('[path]', 'Path to static files (dist/, build/, out/)').option('-b, --build <id>', 'Build ID to attach preview to').option('--base <path>', 'Override auto-detected base path').option('--open', 'Open preview URL in browser after upload').option('--dry-run', 'Show what would be uploaded without uploading').option('--public-link', 'Acknowledge that preview URL grants access to anyone with the link (required for private projects)').option('-x, --exclude <pattern>', 'Exclude files/dirs (repeatable, e.g. -x "*.log" -x "temp/")', (val, prev) => prev ? [...prev, val] : [val]).option('-i, --include <pattern>', 'Override default exclusions (repeatable, e.g. -i package.json -i tests/)', (val, prev) => prev ? [...prev, val] : [val]).action(async (path, options) => {
   const globalOptions = program.opts();
 
   // Show helpful error if path is missing
@@ -747,4 +892,14 @@ program.command('whoami').description('Show current authentication status and us
 // Save user's PATH for menubar app (non-blocking, runs in background)
 // This auto-configures the menubar app so it can find npx/node
 saveUserPath().catch(() => {});
-program.parse();
+let commandNames = new Set(program.commands.map(command => command.name()));
+let normalizedArgv = normalizeJsonArgv(process.argv, commandNames);
+let normalizedGlobals = extractGlobalOptionsFromArgv(normalizedArgv, commandNames);
+output.configure({
+  logLevel: normalizedGlobals.logLevelArg,
+  verbose: normalizedGlobals.verboseMode,
+  color: colorOverride,
+  json: normalizedGlobals.jsonArg,
+  resetTimer: false
+});
+program.parse(normalizedArgv);

package/dist/client/index.js

@@ -8,16 +8,17 @@ 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';
+import { createScreenshotProperties } from '../utils/screenshot-options.js';
 
 // Internal client state
 let currentClient = null;
 let isDisabled = false;
 
 // Default timeout for screenshot requests (30 seconds)
-const DEFAULT_TIMEOUT_MS = 30000;
+let DEFAULT_TIMEOUT_MS = 30000;
 
 // Log levels for client SDK output control
-export const LOG_LEVELS = {
+export let LOG_LEVELS = {
   debug: 0,
   info: 1,
   warn: 2,
@@ -71,14 +72,14 @@ export function autoDiscoverTddServer(startDir, deps = {}) {
   try {
     // Look for .vizzly/server.json in current directory and parent directories
     let currentDir = startDir || process.cwd();
-    const root = parse(currentDir).root;
+    let root = parse(currentDir).root;
     while (currentDir !== root) {
-      const serverJsonPath = join(currentDir, '.vizzly', 'server.json');
+      let serverJsonPath = join(currentDir, '.vizzly', 'server.json');
       if (exists(serverJsonPath)) {
         try {
-          const serverInfo = JSON.parse(readFile(serverJsonPath, 'utf8'));
+          let serverInfo = JSON.parse(readFile(serverJsonPath, 'utf8'));
           if (serverInfo.port) {
-            const url = `http://localhost:${serverInfo.port}`;
+            let url = `http://localhost:${serverInfo.port}`;
             return url;
           }
         } catch {
@@ -191,14 +192,9 @@ function createSimpleClient(serverUrl) {
         let isFilePath = typeof imageBuffer === 'string';
         let image = isFilePath ? imageBuffer : imageBuffer.toString('base64');
         let type = isFilePath ? 'file-path' : 'base64';
-        let {
-          fullPage,
-          threshold,
-          properties: userProperties,
-          ...rest
-        } = options;
+        let properties = createScreenshotProperties(options);
         let httpStart = Date.now();
-        const {
+        let {
           status,
           json
         } = await httpPost(`${serverUrl}/screenshot`, {
@@ -206,11 +202,7 @@ function createSimpleClient(serverUrl) {
           name,
           image,
           type,
-          properties: {
-            ...rest,
-            ...userProperties
-          },
-          fullPage: fullPage || false
+          properties
         }, DEFAULT_TIMEOUT_MS);
         let httpMs = Date.now() - httpStart;
         if (shouldLogClient('debug')) {
@@ -293,10 +285,11 @@ function createSimpleClient(serverUrl) {
  * @param {Buffer|string} imageBuffer - PNG image data as a Buffer, or a file path to an image
  * @param {Object} [options] - Optional configuration
  * @param {Record<string, any>} [options.properties] - Additional properties to attach to the screenshot
- * @param {number} [options.threshold=0] - Pixel difference threshold (0-100)
- * @param {boolean} [options.fullPage=false] - Whether this is a full page screenshot
+ * @param {number} [options.threshold] - CIEDE2000 Delta E threshold for this screenshot
+ * @param {number} [options.minClusterSize] - Minimum changed cluster size for this screenshot
+ * @param {boolean} [options.fullPage] - Whether this is a full page screenshot
  *
- * @returns {Promise<void>}
+ * @returns {Promise<Object|null>} Screenshot result from the server, or null when capture is skipped
  *
  * @example
  * // Basic usage with Buffer
@@ -319,19 +312,17 @@ function createSimpleClient(serverUrl) {
  *   threshold: 5
  * });
  *
- * @throws {VizzlyError} When screenshot capture fails or client is not initialized
- * @throws {VizzlyError} When file path is provided but file doesn't exist
- * @throws {VizzlyError} When file cannot be read due to permissions or I/O errors
+ * Capture failures are logged and return null so test suites can continue.
  */
 export async function vizzlyScreenshot(name, imageBuffer, options = {}) {
   if (isVizzlyDisabled()) {
-    return; // Silently skip when disabled
+    return null; // Silently skip when disabled
   }
   let client = getClient();
   if (!client) {
     // Silently disable - no server running, nothing to do
     disableVizzly();
-    return;
+    return null;
   }
 
   // Pass through the original value (Buffer or file path)
@@ -342,7 +333,7 @@ export async function vizzlyScreenshot(name, imageBuffer, options = {}) {
 /**
  * Wait for all queued screenshots to be processed
  *
- * @returns {Promise<void>}
+ * @returns {Promise<Object|null>} Flush summary, or null if no server is connected
  *
  * @example
  * afterAll(async () => {
@@ -350,10 +341,11 @@ export async function vizzlyScreenshot(name, imageBuffer, options = {}) {
  * });
  */
 export async function vizzlyFlush() {
-  const client = getClient();
+  let client = getClient();
   if (client) {
     return client.flush();
   }
+  return null;
 }
 
 /**
@@ -401,7 +393,7 @@ export function setEnabled(enabled) {
  * @returns {Object} Client information
  */
 export function getVizzlyInfo() {
-  const client = getClient();
+  let client = getClient();
   return {
     enabled: !isVizzlyDisabled(),
     serverUrl: getServerUrl(),