@vizzly-testing/cli 0.39.1 → 0.39.2

package/dist/domains/context/context.commands.js

@@ -0,0 +1,385 @@
+/** Context command orchestration and provider selection. */
+
+import * as defaultOutput from '../../shared/output.js';
+import { createApiClient as defaultCreateApiClient } from '../auth/cloud-client.js';
+import { loadConfig as defaultLoadConfig } from '../config/config-loader.js';
+import { readSession as defaultReadSession } from '../runs/session-store.js';
+import { validateCompactContext, validateCompactOutputSize } from './compact-context.validations.js';
+import { buildCompactBuildPayload, buildCompactComparisonPayload, buildCompactContextRequest, buildScopeQuery } from './context.serializers.js';
+import { getBuildContext as defaultGetBuildContext, getComparisonContext as defaultGetComparisonContext, getReviewQueueContext as defaultGetReviewQueueContext, getScreenshotContext as defaultGetScreenshotContext, getSimilarFingerprintContext as defaultGetSimilarFingerprintContext } from './context.service.js';
+import { displayBuildContext, displayCompactBuildContext, displayCompactComparisonContext, displayComparisonContext, displayFingerprintContext, displayReviewQueueContext, displayScreenshotContext } from './context-presentation.js';
+import { createLocalWorkspaceContextProvider as defaultCreateLocalWorkspaceContextProvider } from './local-workspace-provider.js';
+import { resolveContextSource as defaultResolveContextSource } from './provider-resolver.js';
+function buildAuthErrorMessage() {
+  return 'Authentication required. Use --token, set VIZZLY_TOKEN, run "vizzly login", or link a project.';
+}
+function hasExplicitCloudScope(options = {}, config = {}) {
+  return Boolean(options.org || options.project || config.linkedProject?.organizationSlug || config.linkedProject?.projectSlug);
+}
+function createClient(config, createApiClient) {
+  return createApiClient({
+    baseUrl: config.apiUrl,
+    token: config.apiKey || config.userToken,
+    command: 'context'
+  });
+}
+
+/**
+ * Attach the provider that produced a context payload.
+ *
+ * Context endpoints return API-owned evidence, while source selection belongs
+ * to the CLI. Keeping both in one payload prevents follow-up agent commands
+ * from silently crossing between cloud and local evidence.
+ *
+ * @param {Object} context - Context payload returned by a provider.
+ * @param {string} source - Provider source selected by the CLI.
+ * @returns {Object} Context payload with explicit source provenance.
+ */
+function attachContextSource(context, source) {
+  return {
+    ...context,
+    source
+  };
+}
+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 && !config.userToken) {
+    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, query) {
+      return attachContextSource(await getBuildContext(client, buildId, query), 'cloud');
+    },
+    async getComparisonContext(comparisonId, query) {
+      return attachContextSource(await getComparisonContext(client, comparisonId, query), 'cloud');
+    },
+    async getScreenshotContext(screenshotName, query) {
+      return attachContextSource(await getScreenshotContext(client, screenshotName, query), 'cloud');
+    },
+    async getSimilarFingerprintContext(fingerprintHash, query) {
+      return attachContextSource(await getSimilarFingerprintContext(client, fingerprintHash, query), 'cloud');
+    },
+    async getReviewQueueContext(query) {
+      return attachContextSource(await getReviewQueueContext(client, query), 'cloud');
+    }
+  };
+}
+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 resolveBuildContextId(buildId, runtime, deps = {}) {
+  let {
+    readSession = defaultReadSession
+  } = deps;
+  if (buildId !== 'current' || runtime.source !== 'cloud') {
+    return buildId;
+  }
+  let session = readSession({
+    cwd: runtime.projectRoot
+  });
+  if (session?.buildId && !session.expired) {
+    return session.buildId;
+  }
+  let error = new Error('No current cloud build found. Run "vizzly run" first, or pass a build ID.');
+  error.code = 'NO_CURRENT_CLOUD_BUILD';
+  throw 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,
+    hasCloudScope: hasExplicitCloudScope(options, config)
+  }, {
+    createLocalWorkspaceContextProvider
+  });
+  if (source === 'cloud' && !config.apiKey && !config.userToken) {
+    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
+  };
+}
+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;
+    }
+    let resolvedBuildId = resolveBuildContextId(buildId, runtime, deps);
+    let {
+      compact,
+      details,
+      include,
+      query
+    } = buildCompactContextRequest(options, globalOptions);
+    output.startSpinner('Fetching build context...');
+    let context = await runtime.provider.getBuildContext(resolvedBuildId, query);
+    output.stopSpinner();
+    if (compact) {
+      let compactContext = validateCompactContext(context, 'build');
+      let payload = validateCompactOutputSize(buildCompactBuildPayload(compactContext, include, options.cursor), 'build', details);
+      if (globalOptions.json) {
+        output.data(payload);
+      } else {
+        displayCompactBuildContext(output, payload);
+      }
+      output.cleanup();
+      return;
+    }
+    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 {
+      compact,
+      details,
+      include,
+      query
+    } = buildCompactContextRequest(options, globalOptions);
+    output.startSpinner('Fetching comparison context...');
+    let context = await runtime.provider.getComparisonContext(comparisonId, query);
+    output.stopSpinner();
+    if (compact) {
+      let compactContext = validateCompactContext(context, 'comparison');
+      let payload = validateCompactOutputSize(buildCompactComparisonPayload(compactContext, include), 'comparison', details);
+      if (globalOptions.json) {
+        output.data(payload);
+      } else {
+        displayCompactComparisonContext(output, payload);
+      }
+      output.cleanup();
+      return;
+    }
+    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
+    });
+    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);
+  }
+}

package/dist/domains/context/context.serializers.js

@@ -0,0 +1,157 @@
+import { COMPACT_CONTEXT_LIMIT } from './compact-context.validations.js';
+import { parseIncludeOption } from './context.validations.js';
+export function buildCompactContextRequest(options = {}, globalOptions = {}) {
+  let include = parseIncludeOption(options.include);
+  let compact = !options.full && (!globalOptions.json || options.agent);
+  let details = include.includes('diffs') ? 'diffs' : 'summary';
+  return {
+    compact,
+    details,
+    include,
+    query: compact ? {
+      details,
+      limit: COMPACT_CONTEXT_LIMIT,
+      cursor: options.cursor
+    } : undefined
+  };
+}
+export function buildScopeQuery(options = {}, query = {}) {
+  let scopedQuery = {
+    ...query
+  };
+  if (options.project) {
+    scopedQuery.project = options.project;
+  }
+  if (options.org) {
+    scopedQuery.organization = options.org;
+  }
+  return scopedQuery;
+}
+
+/**
+ * Quote a value only when a suggested command needs shell protection.
+ *
+ * Suggested commands are meant to be executable, so names with whitespace or
+ * apostrophes must survive copy and paste without changing their value.
+ *
+ * @param {unknown} value - CLI argument value.
+ * @returns {string} A shell-safe argument for the displayed command.
+ */
+function quoteCommandArgument(value) {
+  let stringValue = String(value);
+  if (/^[A-Za-z0-9._:/-]+$/.test(stringValue)) {
+    return stringValue;
+  }
+  return `'${stringValue.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Recognize both local source labels emitted across supported context shapes.
+ *
+ * @param {Object} context - Normalized context response.
+ * @returns {boolean} Whether follow-up commands must stay in local mode.
+ */
+function isLocalContext(context = {}) {
+  return ['local', 'local_workspace'].includes(context.source);
+}
+
+/**
+ * Keep executable suggestions on the source that produced their evidence.
+ *
+ * Mixed workspaces can contain both a cloud run session and persisted local
+ * TDD results. Pinning either source prevents a follow-up command from
+ * silently crossing that boundary and describing a different build.
+ *
+ * @param {string} command - Base CLI command.
+ * @param {Object} context - Context that produced the command.
+ * @returns {string} Command pinned to its originating source.
+ */
+function appendContextSource(command, context = {}) {
+  let source = isLocalContext(context) ? 'local' : 'cloud';
+  return `${command} --source ${source}`;
+}
+function buildCompactBuildCommands(context = {}, include = [], cursor = null) {
+  let evidence = context.evidence?.items || [];
+  let page = context.evidence?.page || {};
+  let commands = [];
+  let buildTarget = isLocalContext(context) ? 'current' : context.build?.id || null;
+  let firstComparison = evidence.find(item => item.type === 'comparison' && item.id);
+  let firstNamedEvidence = evidence.find(item => item.screenshot_name);
+  if (firstComparison) {
+    commands.push({
+      label: 'Inspect comparison context',
+      command: appendContextSource(`vizzly --json context comparison ${quoteCommandArgument(firstComparison.id)} --agent`, context)
+    });
+  }
+  if (firstNamedEvidence) {
+    let screenshotName = firstNamedEvidence.screenshot_name;
+    commands.push({
+      label: 'Inspect screenshot history',
+      command: appendContextSource(`vizzly --json context screenshot ${quoteCommandArgument(screenshotName)}`, context)
+    });
+  }
+  if (buildTarget && evidence.length > 0 && !include.includes('diffs')) {
+    let cursorFlag = cursor ? ` --cursor ${quoteCommandArgument(cursor)}` : '';
+    commands.push({
+      label: 'Load raw diff diagnostics',
+      command: appendContextSource(`vizzly --json context build ${quoteCommandArgument(buildTarget)} --agent --include diffs${cursorFlag}`, context)
+    });
+  }
+  if (buildTarget && page.has_more && page.next_cursor) {
+    let includeFlag = include.length > 0 ? ` --include ${include.join(',')}` : '';
+    commands.push({
+      label: 'Load next evidence page',
+      command: appendContextSource(`vizzly --json context build ${quoteCommandArgument(buildTarget)} --agent --cursor ${quoteCommandArgument(page.next_cursor)}${includeFlag}`, context)
+    });
+  }
+  if (buildTarget) {
+    commands.push({
+      label: 'Load full build context',
+      command: appendContextSource(`vizzly --json context build ${quoteCommandArgument(buildTarget)} --agent --full`, context)
+    });
+  }
+  return commands;
+}
+export function buildCompactBuildPayload(context, include = [], cursor = null) {
+  return {
+    ...context,
+    resource: 'build_agent_context',
+    suggested_commands: buildCompactBuildCommands(context, include, cursor)
+  };
+}
+function buildCompactComparisonCommands(context = {}, include = []) {
+  let commands = [];
+  let comparisonId = context.comparison?.id;
+  let streams = [['similar_by_fingerprint', 'similar history'], ['recent_by_name', 'recent history']];
+  let includeFlag = include.length > 0 ? ` --include ${include.join(',')}` : '';
+  if (comparisonId && !include.includes('diffs')) {
+    commands.push({
+      label: 'Load raw diff diagnostics',
+      command: appendContextSource(`vizzly --json context comparison ${quoteCommandArgument(comparisonId)} --agent --include diffs`, context)
+    });
+  }
+  for (let [stream, label] of streams) {
+    let page = context.history?.[stream]?.page;
+    if (!comparisonId || !page?.has_more || !page.next_cursor) {
+      continue;
+    }
+    commands.push({
+      label: `Load next ${label} page`,
+      command: appendContextSource(`vizzly --json context comparison ${quoteCommandArgument(comparisonId)} --agent --cursor ${quoteCommandArgument(page.next_cursor)}${includeFlag}`, context)
+    });
+  }
+  if (comparisonId) {
+    commands.push({
+      label: 'Load full comparison context',
+      command: appendContextSource(`vizzly --json context comparison ${quoteCommandArgument(comparisonId)} --agent --full`, context)
+    });
+  }
+  return commands;
+}
+export function buildCompactComparisonPayload(context, include = []) {
+  return {
+    ...context,
+    resource: 'comparison_agent_context',
+    suggested_commands: buildCompactComparisonCommands(context, include)
+  };
+}

package/dist/domains/context/context.service.js

@@ -0,0 +1,76 @@
+import { buildEndpointWithParams } from '../../shared/cloud-protocol.js';
+
+/**
+ * Get a build context bundle at the detail level the caller can consume.
+ *
+ * Passing detail selection to the API keeps compact callers from downloading
+ * raw Honeydiff geometry by default while preserving the unfiltered endpoint
+ * for raw and full context consumers.
+ *
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Build context bundle
+ */
+export async function getBuildContext(client, buildId, options = {}) {
+  let endpoint = buildEndpointWithParams(`/api/sdk/context/builds/${buildId}`, options);
+  return client.request(endpoint);
+}
+
+/**
+ * Get comparison context bundle with similarity and history
+ * @param {Object} client - API client
+ * @param {string} comparisonId - Comparison ID
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Comparison context bundle
+ */
+export async function getComparisonContext(client, comparisonId, options = {}) {
+  let endpoint = buildEndpointWithParams(`/api/sdk/context/comparisons/${comparisonId}`, options);
+  return client.request(endpoint);
+}
+
+/**
+ * Get screenshot context bundle for a screenshot name
+ * @param {Object} client - API client
+ * @param {string} screenshotName - Screenshot name
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Screenshot context bundle
+ */
+export async function getScreenshotContext(client, screenshotName, options = {}) {
+  let encodedName = encodeURIComponent(screenshotName);
+  let endpoint = buildEndpointWithParams(`/api/sdk/context/screenshots/${encodedName}`, options);
+  return client.request(endpoint);
+}
+
+/**
+ * Get project-scoped similar comparisons for a fingerprint hash
+ * @param {Object} client - API client
+ * @param {string} fingerprintHash - Honeydiff fingerprint hash
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Fingerprint context bundle
+ */
+export async function getSimilarFingerprintContext(client, fingerprintHash, options = {}) {
+  let encodedFingerprint = encodeURIComponent(fingerprintHash);
+  let endpoint = buildEndpointWithParams(`/api/sdk/context/fingerprints/${encodedFingerprint}/similar`, options);
+  return client.request(endpoint);
+}
+
+/**
+ * Get pending review queue context for a project
+ * @param {Object} client - API client
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Review queue context bundle
+ */
+export async function getReviewQueueContext(client, options = {}) {
+  let endpoint = buildEndpointWithParams('/api/sdk/context/review-queue', options);
+  return client.request(endpoint);
+}
+
+/**
+ * Get token context (organization and project info)
+ * @param {Object} client - API client
+ * @returns {Promise<Object>} Token context data
+ */
+export async function getTokenContext(client) {
+  return client.request('/api/sdk/token/context');
+}