@vizzly-testing/cli 0.35.3-beta.0 → 0.35.3-beta.1

package/README.md

@@ -101,7 +101,7 @@ evidence in one place.
 ```bash
 # Cloud context for a build or comparison
 vizzly context build abc123 --source cloud
-vizzly context comparison def456 --source cloud --json
+vizzly context comparison def456 --source cloud --agent --json
 
 # Local workspace context from .vizzly/
 vizzly context build current --source local
@@ -110,9 +110,12 @@ vizzly context screenshot build-detail-screenshots --source local --json
 vizzly context review-queue --source local --json
 ```
 
-`--json` is the durable automation path. `--agent` gives a compact handoff for
-prompt assembly. Add `--full` when you need the whole payload, or
-`--include screenshots,diffs,comments` when compact JSON needs selected detail.
+`--json` is the durable automation path. `--agent` gives you the compact API
+handoff for prompt assembly. Build handoffs contain up to 10 records; use the
+exact next-page command returned in `suggested_commands` to continue safely.
+That command carries the API's opaque `--cursor`. Add
+`--include diffs` for raw diff diagnostics, or `--full` when you need the whole
+payload.
 
 Local context is read-only and file-backed. It reads your existing `.vizzly`
 workspace state from TDD runs, including screenshots, diffs, and saved hotspot

package/dist/api/client.js

@@ -18,6 +18,11 @@ function isProjectToken(token) {
   return typeof token === 'string' && token.startsWith('vzt_');
 }
 
+/** Prefer the transport cause because Node's top-level fetch message is generic. */
+function getNetworkFailureReason(error) {
+  return error?.cause?.code || error?.cause?.message || error?.message || 'request failed';
+}
+
 /**
  * Create an API client with the given configuration
  *
@@ -58,10 +63,19 @@ export function createApiClient(options = {}) {
       contentType: fetchOptions.headers?.['Content-Type'],
       extra: fetchOptions.headers || {}
     });
-    let response = await fetch(url, {
-      ...fetchOptions,
-      headers
-    });
+    let response;
+    try {
+      response = await fetch(url, {
+        ...fetchOptions,
+        headers
+      });
+    } catch (error) {
+      let apiOrigin = new URL(url).origin;
+      let reason = getNetworkFailureReason(error);
+      throw new VizzlyError(`Unable to reach Vizzly at ${apiOrigin}: ${reason}`, 'NETWORK_ERROR', {
+        apiOrigin
+      });
+    }
     if (!response.ok) {
       let errorBody = await extractErrorBody(response);
 
@@ -82,7 +96,8 @@ export function createApiClient(options = {}) {
       // Other errors
       let error = parseApiError(response.status, errorBody, url);
       throw new VizzlyError(error.message, error.code, {
-        status: error.status
+        status: error.status,
+        details: error.details
       });
     }
     return response.json();

package/dist/api/core.js

@@ -232,8 +232,21 @@ export function shouldRetryWithRefresh(status, isRetry, hasRefreshToken) {
  */
 export function parseApiError(status, body, url) {
   let message = `API request failed: ${status}`;
+  let responseDetails = null;
+  let responseCode = null;
+  let responseMessage = body;
   if (body) {
-    message += ` - ${body}`;
+    try {
+      let parsedBody = JSON.parse(body);
+      responseDetails = parsedBody.details ?? null;
+      responseCode = parsedBody.code ?? parsedBody.details?.code ?? null;
+      responseMessage = parsedBody.error ?? parsedBody.message ?? body;
+    } catch {
+      // Plain-text API errors remain valid and are surfaced unchanged.
+    }
+  }
+  if (responseMessage) {
+    message += ` - ${responseMessage}`;
   }
   message += ` (URL: ${url})`;
   let code = 'API_ERROR';
@@ -244,8 +257,9 @@ export function parseApiError(status, body, url) {
   if (status >= 500) code = 'SERVER_ERROR';
   return {
     message,
-    code,
-    status
+    code: responseCode || code,
+    status,
+    details: responseDetails
   };
 }
 

package/dist/cli.js

@@ -3,17 +3,17 @@ import 'dotenv/config';
 import { existsSync, statSync } from 'node:fs';
 import { Option, program } from 'commander';
 import { apiCommand, validateApiOptions } from './commands/api.js';
-import { baselinesCommand, validateBaselinesOptions } from './commands/baselines.js';
+import { baselinesCommand } from './commands/baselines.js';
 import { buildsCommand, validateBuildsOptions } from './commands/builds.js';
 import { comparisonsCommand, validateComparisonsOptions } from './commands/comparisons.js';
-import { configCommand, validateConfigOptions } from './commands/config-cmd.js';
+import { configCommand } 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 { doctorCommand } from './commands/doctor.js';
 import { finalizeCommand, validateFinalizeOptions } from './commands/finalize.js';
 import { init } from './commands/init.js';
-import { loginCommand, validateLoginOptions } from './commands/login.js';
-import { logoutCommand, validateLogoutOptions } from './commands/logout.js';
-import { orgsCommand, validateOrgsOptions } from './commands/orgs.js';
+import { loginCommand } from './commands/login.js';
+import { logoutCommand } from './commands/logout.js';
+import { orgsCommand } 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';
@@ -23,7 +23,7 @@ import { statusCommand, validateStatusOptions } from './commands/status.js';
 import { tddCommand, validateTddOptions } from './commands/tdd.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 { whoamiCommand } from './commands/whoami.js';
 import { createPluginServices } from './plugin-api.js';
 import { loadPlugins } from './plugin-loader.js';
 import { createServices } from './services/index.js';
@@ -651,13 +651,13 @@ Examples:
   await comparisonsCommand(options, globalOptions);
 });
 let contextCmd = program.command('context').description('Fetch build and diff context').showHelpAfterError('(Run vizzly context --help for available commands)').showSuggestionAfterError();
-contextCmd.command('build').description('Fetch build context').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', `
+contextCmd.command('build').description('Fetch build context').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 instead of compact context').option('--cursor <cursor>', 'Continue compact evidence from an opaque API cursor').option('--include <items>', 'Add raw diff diagnostics to compact context: diffs').addHelpText('after', `
 Examples:
   $ vizzly context build abc123 --source cloud
   $ vizzly context build current --source local
   $ vizzly context build current --source local --agent
   $ vizzly context build abc123 --source cloud --agent --json
-  $ vizzly context build abc123 --source cloud --agent --json --include diffs,comments
+  $ vizzly context build abc123 --source cloud --agent --json --include diffs
   $ vizzly context build abc123 --source cloud --agent --json --full
 `).action(async (buildId, options) => {
   let globalOptions = getGlobalOptions();
@@ -667,12 +667,12 @@ Examples:
   }
   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', `
+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('--agent', 'Output compact context for LLM agents').option('--full', 'Return the full comparison context instead of compact context').option('--cursor <cursor>', 'Continue compact history from an opaque API cursor').option('--include <items>', 'Add detail to compact context: diffs').addHelpText('after', `
 Examples:
   $ vizzly context comparison def456 --source cloud
   $ vizzly context comparison def456 --source local
-  $ vizzly context comparison def456 --source cloud --similar-limit 5 --recent-limit 5
   $ vizzly context comparison def456 --source cloud --json
+  $ vizzly context comparison def456 --source cloud --agent --json
 `).action(async (comparisonId, options) => {
   let globalOptions = getGlobalOptions();
   const validationErrors = validateContextComparisonOptions(options);
@@ -724,12 +724,6 @@ Examples:
 });
 program.command('config').description('Display current configuration').argument('[key]', 'Specific config key to get (dot notation, e.g., comparison.threshold)').action(async (key, options) => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateConfigOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await configCommand(key, options, globalOptions);
 });
 program.command('baselines').description('List and query local TDD baselines').option('--name <pattern>', 'Filter baselines by name (supports wildcards)').option('--info <name>', 'Get detailed info for a specific baseline').addHelpText('after', `
@@ -742,12 +736,6 @@ Examples:
 Note: Baselines are stored locally in .vizzly/baselines/ during TDD mode.
 `).action(async options => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateBaselinesOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await baselinesCommand(options, globalOptions);
 });
 program.command('api').description('Make raw API requests (for power users)').argument('<endpoint>', 'API endpoint (e.g., /api/sdk/builds)').option('-X, --method <method>', 'HTTP method (GET or POST for approve/reject/comment)', 'GET').option('-d, --data <json>', 'Request body (JSON)').option('-H, --header <header>', 'Add header (key:value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).option('-q, --query <param>', 'Add query param (key=value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).addHelpText('after', `
@@ -833,10 +821,6 @@ Note: Shows organizations from your user account (via vizzly login)
 or the single organization for a project token.
 `).action(async options => {
   let globalOptions = getGlobalOptions();
-  const validationErrors = validateOrgsOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   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)', Number, 50).option('--offset <n>', 'Skip first N results', Number, 0).addHelpText('after', `
@@ -910,42 +894,18 @@ program.command('preview').description('Upload static files as a preview for a b
 });
 program.command('doctor').description('Run diagnostics to check your environment and configuration').option('--api', 'Include API connectivity checks').action(async options => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateDoctorOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await doctorCommand(options, globalOptions);
 });
 program.command('login').description('Authenticate with your Vizzly account').option('--api-url <url>', 'API URL override').action(async options => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateLoginOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await loginCommand(options, globalOptions);
 });
 program.command('logout').description('Clear stored authentication tokens').option('--api-url <url>', 'API URL override').action(async options => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateLogoutOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await logoutCommand(options, globalOptions);
 });
 program.command('whoami').description('Show current authentication status and user information').option('--api-url <url>', 'API URL override').action(async options => {
   let globalOptions = getGlobalOptions();
-
-  // Validate options
-  const validationErrors = validateWhoamiOptions(options);
-  if (validationErrors.length > 0) {
-    reportValidationErrors(validationErrors);
-  }
   await whoamiCommand(options, globalOptions);
 });
 

package/dist/commands/baselines.js

@@ -286,11 +286,4 @@ export function formatBytes(bytes) {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
-
-/**
- * Validate baselines command options
- */
-export function validateBaselinesOptions() {
-  return [];
 }

package/dist/commands/config-cmd.js

@@ -163,11 +163,4 @@ function getNestedValue(obj, path) {
     current = current[part];
   }
   return current;
-}
-
-/**
- * Validate config command options
- */
-export function validateConfigOptions() {
-  return [];
 }