@vizzly-testing/cli 0.29.5 → 0.30.0

package/README.md

@@ -58,6 +58,33 @@ export VIZZLY_TOKEN=your-project-token
 vizzly run "npm test" --wait
 ```
 
+### Visual Context For Agents
+
+Use `vizzly context` when you want Vizzly to act more like visual context than a test runner.
+
+This is especially useful for LLM agents, automation, and quick debugging loops. Instead of
+making a bunch of narrow API calls, you can ask for one build, comparison, screenshot, or review
+queue bundle and get the evidence in one place.
+
+```bash
+# Cloud context for a build or comparison
+vizzly context build abc123
+vizzly context comparison def456 --json
+
+# Local workspace context from .vizzly/
+vizzly context build current --source local
+vizzly context screenshot build-detail-screenshots --source local --json
+```
+
+`--json` is the main automation path. Human-readable output is there for quick terminal use, but
+JSON is what you want for scripts, agents, and prompt assembly.
+
+Local context is read-only and file-backed. It reads your existing `.vizzly` workspace state from
+TDD runs, including screenshots, diffs, and any saved hotspot or region metadata.
+
+Cloud context is also read-only right now. That is intentional. It keeps the trust model simple:
+Vizzly helps you see and inspect visual changes, while people still decide what gets approved.
+
 ## Capture Screenshots
 
 Add screenshots to your existing tests:
@@ -116,6 +143,7 @@ export default {
 | `vizzly tdd start` | Start local TDD server with dashboard |
 | `vizzly tdd run "cmd"` | Run tests once, generate static report |
 | `vizzly run "cmd"` | Run tests with cloud integration |
+| `vizzly context ...` | Fetch visual context bundles for builds, comparisons, and screenshots |
 | `vizzly upload <dir>` | Upload existing screenshots |
 | `vizzly login` | Authenticate via browser |
 | `vizzly doctor` | Validate local setup |

package/dist/api/endpoints.js

@@ -210,6 +210,65 @@ export async function getComparison(client, comparisonId) {
   return response.comparison;
 }
 
+/**
+ * Get build context bundle for agent and reviewer workflows
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @returns {Promise<Object>} Build context bundle
+ */
+export async function getBuildContext(client, buildId) {
+  return client.request(`/api/sdk/context/builds/${buildId}`);
+}
+
+/**
+ * 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);
+}
+
 /**
  * Search for comparisons by name
  * @param {Object} client - API client

package/dist/api/index.js

@@ -16,4 +16,4 @@ export { createApiClient, DEFAULT_API_URL } from './client.js';
 export { buildApiUrl, buildAuthHeader, buildBuildPayload, buildEndpointWithParams, buildQueryParams, buildRequestHeaders, buildScreenshotCheckObject, buildScreenshotPayload, buildShaCheckPayload, buildUserAgent, computeSha256, extractErrorBody, findScreenshotBySha, isAuthError, isRateLimited, parseApiError, partitionByShaExistence, shaExists, shouldRetryWithRefresh } from './core.js';
 
 // Endpoint functions
-export { checkShas, createBuild, finalizeBuild, finalizeParallelBuild, getBatchHotspots, getBuild, getBuilds, getComparison, getPreviewInfo, getScreenshotHotspots, getTddBaselines, getTokenContext, searchComparisons, updateBuildStatus, uploadPreviewZip, uploadScreenshot } from './endpoints.js';
+export { checkShas, createBuild, finalizeBuild, finalizeParallelBuild, getBatchHotspots, getBuild, getBuildContext, getBuilds, getComparison, getComparisonContext, getPreviewInfo, getReviewQueueContext, getScreenshotContext, getScreenshotHotspots, getSimilarFingerprintContext, getTddBaselines, getTokenContext, searchComparisons, updateBuildStatus, uploadPreviewZip, uploadScreenshot } from './endpoints.js';

package/dist/auth/core.js

@@ -162,7 +162,7 @@ export function buildTokenData(response, existingUser = null) {
  * @returns {{ valid: boolean, error: Error|null }}
  */
 export function validateTokens(auth, requiredField = 'accessToken') {
-  if (!auth || !auth[requiredField]) {
+  if (!auth?.[requiredField]) {
     let message = requiredField === 'refreshToken' ? 'No refresh token found. Please run "vizzly login" first.' : 'No authentication token found. Please run "vizzly login" first.';
     return {
       valid: false,

package/dist/auth/index.js

@@ -9,13 +9,14 @@
 
 // Re-export token store utilities for convenience
 import { clearAuthTokens, getAuthTokens, saveAuthTokens } from '../utils/global-config.js';
-export { clearAuthTokens, getAuthTokens, saveAuthTokens };
+
 // HTTP client factory
 export { createAuthClient } from './client.js';
 // Core pure functions
 export { buildAuthHeader, buildAuthUserAgent, buildDevicePollPayload, buildLogoutPayload, buildRefreshPayload, buildRequestHeaders, buildTokenData, parseAuthError, parseAuthenticatedError, validateTokens } from './core.js';
 // Auth operations (take dependencies as parameters)
 export { completeDeviceFlow, initiateDeviceFlow, isAuthenticated, logout, pollDeviceAuthorization, refresh, whoami } from './operations.js';
+export { clearAuthTokens, getAuthTokens, saveAuthTokens };
 
 /**
  * Create a token store adapter from global-config functions

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';
@@ -71,7 +72,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: '▸',
@@ -202,40 +203,65 @@ const formatHelp = (cmd, helper) => {
   lines.push('');
   return lines.join('\n');
 };
+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 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({
   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')
@@ -479,6 +505,96 @@ Examples:
   }
   await comparisonsCommand(options, globalOptions);
 });
+let contextCmd = program.command('context').description('Fetch visual context bundles for agents and reviewers');
+contextCmd.command('build').description('Fetch a build context bundle').argument('<build-id>', 'Build ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').addHelpText('after', `
+Examples:
+  $ vizzly context build abc123
+  $ vizzly context build current --source local
+  $ vizzly context build abc123 --json
+  $ vizzly context build abc123 --json build.id,summary.comparisons
+`).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)', val => parseInt(val, 10)).option('--recent-limit <n>', 'Maximum recent same-name comparisons to return (1-50)', val => parseInt(val, 10)).option('--window-size <n>', 'Historical hotspot analysis window size (1-50)', val => parseInt(val, 10)).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)', val => parseInt(val, 10)).option('--window-size <n>', 'Historical hotspot analysis window size (1-50)', val => parseInt(val, 10)).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)', val => parseInt(val, 10)).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)', val => parseInt(val, 10)).option('--offset <n>', 'Skip first N comparisons', val => parseInt(val, 10)).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();
 
@@ -747,4 +863,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);