@vizzly-testing/cli 0.29.5 → 0.30.0

package/dist/commands/context.js

@@ -0,0 +1,559 @@
+/**
+ * Context commands - fetch visual context bundles for agents and reviewers
+ */
+
+import { createApiClient as defaultCreateApiClient, getBuildContext as defaultGetBuildContext, getComparisonContext as defaultGetComparisonContext, getReviewQueueContext as defaultGetReviewQueueContext, getScreenshotContext as defaultGetScreenshotContext, getSimilarFingerprintContext as defaultGetSimilarFingerprintContext } from '../api/index.js';
+import { createLocalWorkspaceContextProvider as defaultCreateLocalWorkspaceContextProvider } from '../context/local-workspace-provider.js';
+import { resolveContextSource as defaultResolveContextSource } from '../context/provider-resolver.js';
+import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
+import * as defaultOutput from '../utils/output.js';
+function buildAuthErrorMessage() {
+  return 'API token required. Use --token, set VIZZLY_TOKEN, or run "vizzly login"';
+}
+function buildSourceErrorMessage() {
+  return '--source must be one of: auto, cloud, local';
+}
+function validateLimitRange(value, flagName, {
+  min = 1,
+  max
+}) {
+  if (value == null) {
+    return [];
+  }
+  if (!Number.isInteger(value) || value < min || value > max) {
+    return [`${flagName} must be a number between ${min} and ${max}`];
+  }
+  return [];
+}
+function validateOffset(value) {
+  if (value == null) {
+    return [];
+  }
+  if (!Number.isInteger(value) || value < 0) {
+    return ['--offset must be a non-negative number'];
+  }
+  return [];
+}
+function validateSourceOption(value) {
+  if (value == null) {
+    return [];
+  }
+  if (!['auto', 'cloud', 'local'].includes(value)) {
+    return [buildSourceErrorMessage()];
+  }
+  return [];
+}
+function validateScopedProjectOptions(options = {}) {
+  let errors = [];
+  if (options.org && !options.project) {
+    errors.push('--org requires --project');
+  }
+  return errors;
+}
+function createClient(config, createApiClient) {
+  return createApiClient({
+    baseUrl: config.apiUrl,
+    token: config.apiKey,
+    command: 'context'
+  });
+}
+async function loadContextConfig(globalOptions, options, deps) {
+  let {
+    loadConfig = defaultLoadConfig,
+    requireApiKey = true,
+    output = defaultOutput,
+    exit = code => process.exit(code)
+  } = deps;
+  let allOptions = {
+    ...globalOptions,
+    ...options
+  };
+  let config = await loadConfig(globalOptions.config, allOptions);
+  if (requireApiKey && !config.apiKey) {
+    output.error(buildAuthErrorMessage());
+    output.cleanup();
+    exit(1);
+    return null;
+  }
+  return config;
+}
+function createCloudContextProvider(config, deps = {}) {
+  let {
+    createApiClient = defaultCreateApiClient,
+    getBuildContext = defaultGetBuildContext,
+    getComparisonContext = defaultGetComparisonContext,
+    getScreenshotContext = defaultGetScreenshotContext,
+    getSimilarFingerprintContext = defaultGetSimilarFingerprintContext,
+    getReviewQueueContext = defaultGetReviewQueueContext
+  } = deps;
+  let client = createClient(config, createApiClient);
+  return {
+    source: 'cloud',
+    async getBuildContext(buildId) {
+      return await getBuildContext(client, buildId);
+    },
+    async getComparisonContext(comparisonId, query) {
+      return await getComparisonContext(client, comparisonId, query);
+    },
+    async getScreenshotContext(screenshotName, query) {
+      return await getScreenshotContext(client, screenshotName, query);
+    },
+    async getSimilarFingerprintContext(fingerprintHash, query) {
+      return await getSimilarFingerprintContext(client, fingerprintHash, query);
+    },
+    async getReviewQueueContext(query) {
+      return await getReviewQueueContext(client, query);
+    }
+  };
+}
+function buildLocalFingerprintCapabilityError() {
+  let error = new Error('Local workspace context does not support fingerprint similarity yet. Use --source cloud for this query.');
+  error.code = 'LOCAL_WORKSPACE_CONTEXT';
+  return error;
+}
+function shouldExplainLocalSimilarityGap(requestedSource, command, localProvider) {
+  return requestedSource === 'auto' && command === 'similar' && localProvider.isAvailable();
+}
+async function loadContextRuntime(command, target, globalOptions, options, deps = {}) {
+  let {
+    createLocalWorkspaceContextProvider = defaultCreateLocalWorkspaceContextProvider,
+    resolveContextSource = defaultResolveContextSource,
+    output = defaultOutput,
+    exit = code => process.exit(code)
+  } = deps;
+  let config = await loadContextConfig(globalOptions, options, {
+    ...deps,
+    output,
+    exit,
+    requireApiKey: false
+  });
+  let requestedSource = options.source || 'auto';
+  let projectRoot = deps.projectRoot || process.cwd();
+  let localProvider = createLocalWorkspaceContextProvider({
+    projectRoot
+  });
+  let source = resolveContextSource({
+    requestedSource,
+    command,
+    target,
+    projectRoot
+  }, {
+    createLocalWorkspaceContextProvider
+  });
+  if (source === 'cloud' && !config.apiKey) {
+    if (shouldExplainLocalSimilarityGap(requestedSource, command, localProvider)) {
+      throw buildLocalFingerprintCapabilityError();
+    }
+    output.error(buildAuthErrorMessage());
+    output.cleanup();
+    exit(1);
+    return null;
+  }
+  let provider = source === 'local' ? localProvider : createCloudContextProvider(config, deps);
+  return {
+    config,
+    source,
+    provider
+  };
+}
+function buildScopeQuery(options = {}, query = {}) {
+  let scopedQuery = {
+    ...query
+  };
+  if (options.project) {
+    scopedQuery.project = options.project;
+  }
+  if (options.org) {
+    scopedQuery.organization = options.org;
+  }
+  return scopedQuery;
+}
+function getStatusTone(colors, status) {
+  if (status === 'changed' || status === 'pending' || status === 'failed') {
+    return colors.brand.warning;
+  }
+  if (status === 'approved' || status === 'completed' || status === 'identical') {
+    return colors.brand.success;
+  }
+  if (status === 'rejected' || status === 'error') {
+    return colors.brand.error;
+  }
+  return colors.brand.info;
+}
+function getComparisonDisplayState(comparison = {}) {
+  return comparison.result || comparison.status || 'unknown';
+}
+function formatConfirmedRegionLabels(regions = []) {
+  return regions.map(region => region.label).filter(Boolean).slice(0, 3).join(' · ');
+}
+function printComparisonList(output, comparisons = [], {
+  limit = 5
+} = {}) {
+  let colors = output.getColors();
+  for (let comparison of comparisons.slice(0, limit)) {
+    let displayState = getComparisonDisplayState(comparison);
+    let statusTone = getStatusTone(colors, displayState);
+    let screenshotName = comparison.screenshot?.name || comparison.name || comparison.id;
+    let diffPercentage = comparison.diff_percentage == null ? null : `${comparison.diff_percentage}%`;
+    let fingerprint = comparison.analysis?.fingerprint_hash || null;
+    let details = [];
+    if (diffPercentage) {
+      details.push(diffPercentage);
+    }
+    if (fingerprint) {
+      details.push(`fp:${fingerprint}`);
+    }
+    if (comparison.build_branch) {
+      details.push(comparison.build_branch);
+    }
+    output.print(`  ${colors.bold(screenshotName)} ${statusTone(displayState.toUpperCase())}`);
+    if (details.length > 0) {
+      output.print(`    ${colors.dim(details.join(' · '))}`);
+    }
+  }
+}
+function displayBuildContext(output, context) {
+  output.header('context', 'build');
+  let colors = output.getColors();
+  let buildTone = getStatusTone(colors, context.build.status);
+  output.print(`  ${colors.bold(context.build.name || context.build.id)} ${buildTone((context.build.status || 'unknown').toUpperCase())}`);
+  output.print(`  ${colors.dim(`@${context.scope.organization.slug}/${context.scope.project.slug}`)}`);
+  output.blank();
+  output.labelValue('Comparisons', String(context.comparisons.length));
+  output.labelValue('Review', `${context.summary.review.pending || 0} pending · ${context.summary.review.approved || 0} approved · ${context.summary.review.rejected || 0} rejected`);
+  output.labelValue('Memory', `${context.review.comments.length} build comments · ${context.review.assignments.length} assignments`);
+  if (context.preview) {
+    output.labelValue('Preview', `${context.preview.status}${context.preview.preview_url ? ' · available' : ''}`);
+  }
+  if (context.links?.build_url) {
+    output.labelValue('Build URL', context.links.build_url);
+  }
+  if (context.comparisons.length > 0) {
+    output.blank();
+    output.print('  Comparisons');
+    printComparisonList(output, context.comparisons);
+  }
+}
+function countScreenshotCommentEntries(groups = []) {
+  return groups.reduce((total, group) => total + (group.comments?.length || 0), 0);
+}
+function displayComparisonContext(output, context) {
+  output.header('context', 'comparison');
+  let colors = output.getColors();
+  let displayState = getComparisonDisplayState(context.comparison);
+  let statusTone = getStatusTone(colors, displayState);
+  let screenshotName = context.comparison.screenshot?.name || context.comparison.id;
+  let analysis = context.comparison.analysis || {};
+  let confirmedRegionLabels = formatConfirmedRegionLabels(context.history.confirmed_regions);
+  output.print(`  ${colors.bold(screenshotName)} ${statusTone(displayState.toUpperCase())}`);
+  output.print(`  ${colors.dim(`@${context.scope.organization.slug}/${context.scope.project.slug}`)}`);
+  output.blank();
+  output.labelValue('Eyes', `${analysis.diff_image_url ? 'baseline/current/diff' : 'comparison metadata only'}`);
+  output.labelValue('Memory', `${context.history.similar_by_fingerprint.length} similar · ${context.history.recent_by_name.length} recent · ${context.history.confirmed_regions.length} confirmed regions`);
+  output.labelValue('Review', `${context.review.build_comments.length} build comments · ${countScreenshotCommentEntries(context.review.screenshot_comments)} screenshot comments`);
+  if (analysis.fingerprint_hash) {
+    output.labelValue('Fingerprint', analysis.fingerprint_hash);
+  }
+  if (confirmedRegionLabels) {
+    output.labelValue('Known Regions', confirmedRegionLabels);
+  }
+  if (context.links?.comparison_url) {
+    output.labelValue('Comparison URL', context.links.comparison_url);
+  }
+  if (context.history.similar_by_fingerprint.length > 0) {
+    output.blank();
+    output.print('  Similar Diffs');
+    printComparisonList(output, context.history.similar_by_fingerprint);
+  }
+}
+function displayScreenshotContext(output, context) {
+  output.header('context', 'screenshot');
+  let colors = output.getColors();
+  let confirmedRegionLabels = formatConfirmedRegionLabels(context.confirmed_regions);
+  output.print(`  ${colors.bold(context.screenshot.name)}`);
+  output.print(`  ${colors.dim(`@${context.scope.organization.slug}/${context.scope.project.slug}`)}`);
+  output.blank();
+  output.labelValue('Memory', `${context.history.recent_comparisons.length} recent comparisons · ${context.confirmed_regions.length} confirmed regions`);
+  output.labelValue('Hotspots', `${context.hotspot_analysis.total_builds_analyzed} builds analyzed · ${context.hotspot_analysis.confidence}`);
+  if (confirmedRegionLabels) {
+    output.labelValue('Known Regions', confirmedRegionLabels);
+  }
+  if (context.history.recent_comparisons.length > 0) {
+    output.blank();
+    output.print('  Recent Comparisons');
+    printComparisonList(output, context.history.recent_comparisons);
+  }
+}
+function displayFingerprintContext(output, context) {
+  output.header('context', 'similar');
+  let colors = output.getColors();
+  let fingerprintHash = context.fingerprint?.hash || context.fingerprint_hash || 'unknown';
+  let comparisons = context.comparisons || context.matches || [];
+  output.print(`  ${colors.bold(fingerprintHash)}`);
+  output.print(`  ${colors.dim(`@${context.scope.organization.slug}/${context.scope.project.slug}`)}`);
+  output.blank();
+  output.labelValue('Matches', String(comparisons.length));
+  if (comparisons.length > 0) {
+    output.blank();
+    output.print('  Similar Diffs');
+    printComparisonList(output, comparisons, {
+      limit: 10
+    });
+  }
+}
+function displayReviewQueueContext(output, context) {
+  output.header('context', 'review');
+  let colors = output.getColors();
+  output.print(`  ${colors.bold(`${context.summary.total} pending comparisons`)}`);
+  output.print(`  ${colors.dim(`@${context.scope.organization.slug}/${context.scope.project.slug}`)}`);
+  output.blank();
+  output.labelValue('Queue', `${context.summary.changed} changed · ${context.summary.new} new · ${context.summary.builds} builds`);
+  if (context.comparisons.length > 0) {
+    output.blank();
+    output.print('  Needs Review');
+    printComparisonList(output, context.comparisons, {
+      limit: 10
+    });
+  }
+}
+export async function contextBuildCommand(buildId, options = {}, globalOptions = {}, deps = {}) {
+  let {
+    output = defaultOutput,
+    exit = code => process.exit(code)
+  } = deps;
+  output.configure({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    let runtime = await loadContextRuntime('build', buildId, globalOptions, options, {
+      ...deps,
+      output,
+      exit
+    });
+    if (!runtime) {
+      return;
+    }
+    output.startSpinner('Fetching build context...');
+    let context = await runtime.provider.getBuildContext(buildId);
+    output.stopSpinner();
+    if (globalOptions.json) {
+      output.data(context);
+      output.cleanup();
+      return;
+    }
+    displayBuildContext(output, context);
+    output.cleanup();
+  } catch (error) {
+    output.stopSpinner();
+    output.error('Failed to fetch build context', error);
+    output.cleanup();
+    exit(1);
+  }
+}
+export async function contextComparisonCommand(comparisonId, options = {}, globalOptions = {}, deps = {}) {
+  let {
+    output = defaultOutput,
+    exit = code => process.exit(code)
+  } = deps;
+  output.configure({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    let runtime = await loadContextRuntime('comparison', comparisonId, globalOptions, options, {
+      ...deps,
+      output,
+      exit
+    });
+    if (!runtime) {
+      return;
+    }
+    let query = {
+      similarLimit: options.similarLimit,
+      recentLimit: options.recentLimit,
+      windowSize: options.windowSize
+    };
+    output.startSpinner('Fetching comparison context...');
+    let context = await runtime.provider.getComparisonContext(comparisonId, query);
+    output.stopSpinner();
+    if (globalOptions.json) {
+      output.data(context);
+      output.cleanup();
+      return;
+    }
+    displayComparisonContext(output, context);
+    output.cleanup();
+  } catch (error) {
+    output.stopSpinner();
+    output.error('Failed to fetch comparison context', error);
+    output.cleanup();
+    exit(1);
+  }
+}
+export async function contextScreenshotCommand(screenshotName, options = {}, globalOptions = {}, deps = {}) {
+  let {
+    output = defaultOutput,
+    exit = code => process.exit(code)
+  } = deps;
+  output.configure({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    let runtime = await loadContextRuntime('screenshot', screenshotName, globalOptions, options, {
+      ...deps,
+      output,
+      exit
+    });
+    if (!runtime) {
+      return;
+    }
+    let query = buildScopeQuery(options, {
+      recentLimit: options.recentLimit,
+      windowSize: options.windowSize
+    });
+    output.startSpinner('Fetching screenshot context...');
+    let context = await runtime.provider.getScreenshotContext(screenshotName, query);
+    output.stopSpinner();
+    if (globalOptions.json) {
+      output.data(context);
+      output.cleanup();
+      return;
+    }
+    displayScreenshotContext(output, context);
+    output.cleanup();
+  } catch (error) {
+    output.stopSpinner();
+    output.error('Failed to fetch screenshot context', error);
+    output.cleanup();
+    exit(1);
+  }
+}
+export async function contextSimilarCommand(fingerprintHash, options = {}, globalOptions = {}, deps = {}) {
+  let {
+    output = defaultOutput,
+    exit = code => process.exit(code)
+  } = deps;
+  output.configure({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    let runtime = await loadContextRuntime('similar', fingerprintHash, globalOptions, options, {
+      ...deps,
+      output,
+      exit
+    });
+    if (!runtime) {
+      return;
+    }
+    let query = buildScopeQuery(options, {
+      limit: options.limit
+    });
+    output.startSpinner('Fetching similar visual context...');
+    let context = await runtime.provider.getSimilarFingerprintContext(fingerprintHash, query);
+    output.stopSpinner();
+    if (globalOptions.json) {
+      output.data(context);
+      output.cleanup();
+      return;
+    }
+    displayFingerprintContext(output, context);
+    output.cleanup();
+  } catch (error) {
+    output.stopSpinner();
+    output.error('Failed to fetch similar visual context', error);
+    output.cleanup();
+    exit(1);
+  }
+}
+export async function contextReviewQueueCommand(options = {}, globalOptions = {}, deps = {}) {
+  let {
+    output = defaultOutput,
+    exit = code => process.exit(code)
+  } = deps;
+  output.configure({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
+  try {
+    let runtime = await loadContextRuntime('review-queue', null, globalOptions, options, {
+      ...deps,
+      output,
+      exit
+    });
+    if (!runtime) {
+      return;
+    }
+    let query = buildScopeQuery(options, {
+      limit: options.limit,
+      offset: options.offset
+    });
+    output.startSpinner('Fetching review queue context...');
+    let context = await runtime.provider.getReviewQueueContext(query);
+    output.stopSpinner();
+    if (globalOptions.json) {
+      output.data(context);
+      output.cleanup();
+      return;
+    }
+    displayReviewQueueContext(output, context);
+    output.cleanup();
+  } catch (error) {
+    output.stopSpinner();
+    output.error('Failed to fetch review queue context', error);
+    output.cleanup();
+    exit(1);
+  }
+}
+export function validateContextBuildOptions(_options = {}) {
+  return validateSourceOption(_options.source);
+}
+export function validateContextComparisonOptions(options = {}) {
+  let errors = [];
+  errors.push(...validateSourceOption(options.source));
+  errors.push(...validateLimitRange(options.similarLimit, '--similar-limit', {
+    max: 50
+  }));
+  errors.push(...validateLimitRange(options.recentLimit, '--recent-limit', {
+    max: 50
+  }));
+  errors.push(...validateLimitRange(options.windowSize, '--window-size', {
+    max: 50
+  }));
+  return errors;
+}
+export function validateContextScreenshotOptions(options = {}) {
+  let errors = validateScopedProjectOptions(options);
+  errors.push(...validateSourceOption(options.source));
+  errors.push(...validateLimitRange(options.recentLimit, '--recent-limit', {
+    max: 50
+  }));
+  errors.push(...validateLimitRange(options.windowSize, '--window-size', {
+    max: 50
+  }));
+  return errors;
+}
+export function validateContextSimilarOptions(options = {}) {
+  let errors = validateScopedProjectOptions(options);
+  errors.push(...validateSourceOption(options.source));
+  errors.push(...validateLimitRange(options.limit, '--limit', {
+    max: 50
+  }));
+  return errors;
+}
+export function validateContextReviewQueueOptions(options = {}) {
+  let errors = validateScopedProjectOptions(options);
+  errors.push(...validateSourceOption(options.source));
+  errors.push(...validateLimitRange(options.limit, '--limit', {
+    max: 100
+  }));
+  errors.push(...validateOffset(options.offset));
+  return errors;
+}

package/dist/commands/logout.js

@@ -21,7 +21,7 @@ export async function logoutCommand(options = {}, globalOptions = {}) {
   try {
     // Check if user is logged in
     let auth = await getAuthTokens();
-    if (!auth || !auth.accessToken) {
+    if (!auth?.accessToken) {
       if (globalOptions.json) {
         output.data({
           loggedOut: false,

package/dist/commands/whoami.js

@@ -21,7 +21,7 @@ export async function whoamiCommand(options = {}, globalOptions = {}) {
   try {
     // Check if user is logged in
     let auth = await getAuthTokens();
-    if (!auth || !auth.accessToken) {
+    if (!auth?.accessToken) {
       if (globalOptions.json) {
         output.data({
           authenticated: false

package/dist/config/core.js

@@ -390,7 +390,7 @@ export function serializeConfig(config, filepath) {
  * @returns {{ config: Object|null, filepath: string|null }}
  */
 export function extractCosmiconfigResult(result) {
-  if (!result || !result.config) {
+  if (!result?.config) {
     return {
       config: null,
       filepath: null