@vizzly-testing/cli 0.36.0 → 0.37.0

package/README.md

@@ -62,7 +62,7 @@ For a one-off local check, wrap the test command with `tdd run`:
 
 ```bash
 vizzly tdd run "pnpm test" --no-open
-vizzly context build current --source local --agent
+vizzly context build current --source local --json
 ```
 
 That run writes review data under `.vizzly/` and prints a context command you
@@ -96,38 +96,44 @@ vizzly run "pnpm test" --wait
 
 ### Inspect Builds And Diffs
 
-Use `vizzly context` when you need build, comparison, screenshot, or review
-queue data from the terminal.
+Use `vizzly context` for human summaries and local `.vizzly` evidence. For cloud
+reviews, agents should discover and call the public API through its schema:
 
-This is useful for scripts, coding agents, and debugging loops. Instead of
-making a pile of narrow API calls, ask for one focused bundle and get the
-evidence in one place.
+```bash
+vizzly api schema --json
+vizzly api schema sdk.listBuilds --json
+```
+
+The `context build --agent` and `context comparison --agent` formats are
+deprecated and scheduled for removal in v0.38.0. Use the schema-driven API for
+cloud evidence; use `vizzly context ... --json` for local evidence.
 
 ```bash
-# Cloud context for a build or comparison
+# Human-readable cloud build context
 vizzly context build abc123 --source cloud
-vizzly context comparison def456 --source cloud --agent --json
+
+# Discover cloud evidence operations for an agent workflow
+vizzly api schema sdk.getBuildContext --json
+vizzly api schema getComparisonContext --json
 
 # Local workspace context from .vizzly/
 vizzly context build current --source local
-vizzly context build current --source local --agent
+vizzly context build current --source local --json
 vizzly context screenshot build-detail-screenshots --source local --json
 vizzly context review-queue --source local --json
 ```
 
-`--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.
+Use `vizzly api schema` to inspect cloud operation inputs, output fields, and
+pagination before making requests. The old compact `--agent` handoff remains
+available during deprecation, but new cloud workflows should use the schema.
+Use `--json` for machine-readable local context.
 
 Local context is read-only and file-backed. It reads your existing `.vizzly`
 workspace state from TDD runs, including screenshots, diffs, and saved hotspot
 or region metadata.
 
-Cloud context is also read-only right now. That is intentional. Vizzly helps you
-see and inspect visual changes, while people still decide what gets approved.
+The `context` commands are read-only. The schema-discovered review API also
+supports explicit decisions when a task asks for them.
 
 ## Capture Screenshots
 

package/dist/api/client.js

@@ -56,6 +56,11 @@ export function createApiClient(options = {}) {
    * @returns {Promise<Object>} Parsed JSON response
    */
   async function request(endpoint, fetchOptions = {}, isRetry = false) {
+    let {
+      responseType = 'json',
+      retryAuthentication = true,
+      ...httpOptions
+    } = fetchOptions;
     let url = buildApiUrl(baseUrl, endpoint);
     let headers = buildRequestHeaders({
       token,
@@ -66,7 +71,7 @@ export function createApiClient(options = {}) {
     let response;
     try {
       response = await fetch(url, {
-        ...fetchOptions,
+        ...httpOptions,
         headers
       });
     } catch (error) {
@@ -80,7 +85,7 @@ export function createApiClient(options = {}) {
       let errorBody = await extractErrorBody(response);
 
       // Handle 401 with token refresh
-      if (shouldRetryWithRefresh(response.status, isRetry, !isProjectToken(token) && (await hasRefreshToken()))) {
+      if (retryAuthentication && shouldRetryWithRefresh(response.status, isRetry, !isProjectToken(token) && (await hasRefreshToken()))) {
         let refreshed = await attemptTokenRefresh();
         if (refreshed) {
           token = refreshed;
@@ -100,6 +105,12 @@ export function createApiClient(options = {}) {
         details: error.details
       });
     }
+    if (responseType === 'response') return response;
+    if (response.status === 204 || httpOptions.method === 'HEAD') return null;
+    let contentType = response.headers?.get?.('content-type');
+    if (contentType && !/application\/(?:[\w.+-]+\+)?json\b/i.test(contentType)) {
+      throw new VizzlyError('This response contains file data. Use api --output <file> to download it.', 'BINARY_RESPONSE');
+    }
     return response.json();
   }
 
@@ -122,6 +133,7 @@ export function createApiClient(options = {}) {
       let refreshUrl = buildApiUrl(baseUrl, '/api/auth/cli/refresh');
       let response = await fetch(refreshUrl, {
         method: 'POST',
+        redirect: 'error',
         headers: {
           'Content-Type': 'application/json',
           'User-Agent': userAgent

package/dist/cli.js

@@ -2,7 +2,7 @@
 import 'dotenv/config';
 import { existsSync, statSync } from 'node:fs';
 import { Option, program } from 'commander';
-import { apiCommand, validateApiOptions } from './commands/api.js';
+import { apiCommand, apiSchemaCommand, validateApiOptions } from './commands/api.js';
 import { baselinesCommand } from './commands/baselines.js';
 import { buildsCommand, validateBuildsOptions } from './commands/builds.js';
 import { comparisonsCommand, validateComparisonsOptions } from './commands/comparisons.js';
@@ -357,6 +357,10 @@ function getGlobalOptions() {
     noColor: options.noColor || options.color === false
   };
 }
+function warnDeprecatedContextAgentOption() {
+  let warning = ['`vizzly context --agent` is deprecated and will be removed in v0.38.0.', 'For cloud reviews, use `vizzly api schema --json` and follow the', 'discovered operations. For local evidence, use', '`vizzly context ... --json`.'].join(' ');
+  output.warn(warning);
+}
 function reportValidationErrors(errors) {
   if (output.isJson()) {
     output.error('Validation errors', null, {
@@ -651,30 +655,38 @@ 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 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', `
+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', 'Deprecated; use API schema for cloud review.').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
-  $ vizzly context build abc123 --source cloud --agent --json --full
+  $ vizzly api schema --json
+  $ vizzly context build current --source local --json
+
+Deprecation:
+  --agent will be removed in v0.38.0. Use the API schema for cloud reviews;
+  use --json without --agent for local evidence.
 `).action(async (buildId, options) => {
   let globalOptions = getGlobalOptions();
+  if (options.agent) warnDeprecatedContextAgentOption();
   const validationErrors = validateContextBuildOptions(options);
   if (validationErrors.length > 0) {
     reportValidationErrors(validationErrors);
   }
   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('--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', `
+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', 'Deprecated; use API schema for cloud review.').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 --json
-  $ vizzly context comparison def456 --source cloud --agent --json
+  $ vizzly api schema getComparisonContext --json
+
+Deprecation:
+  --agent will be removed in v0.38.0. Use the API schema for cloud reviews;
+  use --json without --agent for local evidence.
 `).action(async (comparisonId, options) => {
   let globalOptions = getGlobalOptions();
+  if (options.agent) warnDeprecatedContextAgentOption();
   const validationErrors = validateContextComparisonOptions(options);
   if (validationErrors.length > 0) {
     reportValidationErrors(validationErrors);
@@ -738,7 +750,7 @@ Note: Baselines are stored locally in .vizzly/baselines/ during TDD mode.
   let globalOptions = getGlobalOptions();
   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 build comments)', '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', `
+let api = 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; discover supported requests with api schema', 'GET').option('-d, --data <json>', 'JSON body, @file, or @- for stdin').option('-o, --output <file>', 'Write response bytes to a new file').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', `
 Examples:
   $ vizzly api /api/sdk/builds                    # List builds
   $ vizzly api /api/sdk/builds -q limit=5         # With query params
@@ -746,8 +758,10 @@ Examples:
   $ vizzly api /api/sdk/builds/abc123/comments -X POST -d '{"content":"Looks good"}'
   $ vizzly api /api/sdk/builds/abc123/comments -X POST -d '{"content":"Nice!"}'
 
-Note: POST is restricted to build comment endpoints. Use dedicated approve/reject commands for review decisions.
-Most operations have dedicated commands (builds, comparisons, approve, etc.).
+Discover operations: vizzly api schema, then vizzly api schema <operation-id>.
+Use the method, version header, parameters and body described there.
+JSON output places the API payload under data.response. Image downloads use --output.
+Writes are never automatically retried after authentication failures.
 `).action(async (endpoint, options) => {
   let globalOptions = getGlobalOptions();
 
@@ -758,6 +772,17 @@ Most operations have dedicated commands (builds, comparisons, approve, etc.).
   }
   await apiCommand(endpoint, options, globalOptions);
 });
+api.command('schema [operation-id]').description('Discover supported API operations and their request/response schemas').option('--full', 'Download full OpenAPI (requires --output)').option('-q, --query <param>', 'Schema view=request, fields, response, or full', (value, previous) => [...(previous || []), value]).option('-o, --output <file>', 'Write the schema to a new file').action(async (operationId, options) => {
+  options = {
+    ...api.opts(),
+    ...options
+  };
+  if (options.full && !options.output) {
+    reportValidationErrors(['--full requires --output to avoid dumping the entire schema.']);
+    return;
+  }
+  await apiSchemaCommand(operationId, options, getGlobalOptions());
+});
 program.command('approve').description('Approve a comparison').argument('<comparison-id>', 'Comparison ID to approve').option('-m, --comment <message>', 'Optional comment explaining the approval').addHelpText('after', `
 Examples:
   $ vizzly approve abc123-def456-7890     # Approve a comparison
@@ -909,11 +934,11 @@ program.command('whoami').description('Show current authentication status and us
   await whoamiCommand(options, globalOptions);
 });
 
-// Save user's PATH for menubar app (non-blocking, runs in background)
-// This auto-configures the menubar app so it can find package runners/node
-saveUserPath().catch(() => {});
+// Save PATH for the menubar app before commands read or update credentials
+// in the same config file.
+await saveUserPath().catch(() => {});
 let commandNames = new Set(program.commands.map(command => command.name()));
-let nestedCommandNames = new Map(program.commands.map(command => [command.name(), new Set(command.commands.map(subcommand => subcommand.name()))]));
+let nestedCommandNames = new Map(program.commands.map(command => [command.name(), new Set(command.registeredArguments.length ? [] : command.commands.map(subcommand => subcommand.name()))]));
 let normalizedArgv = normalizeJsonArgv(process.argv, commandNames);
 let normalizedGlobals = extractGlobalOptionsFromArgv(normalizedArgv, commandNames);
 output.configure({

package/dist/commands/api.js

@@ -2,10 +2,14 @@
  * API command - raw API access for power users
  */
 
+import { open, readFile, unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 import { createApiClient as defaultCreateApiClient } from '../api/index.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import * as defaultOutput from '../utils/output.js';
-let ALLOWED_POST_ENDPOINTS = [/^\/api\/sdk\/builds\/[^/]+\/comments$/];
+let API_METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'];
 function createApiCommandDeps(deps = {}) {
   return {
     loadConfig: deps.loadConfig || defaultLoadConfig,
@@ -31,9 +35,6 @@ export function normalizeApiEndpoint(endpoint) {
 export function normalizeApiMethod(method = 'GET') {
   return method.toUpperCase();
 }
-export function isAllowedPostEndpoint(endpoint) {
-  return ALLOWED_POST_ENDPOINTS.some(pattern => pattern.test(endpoint));
-}
 export function parseApiHeaders(headerOption) {
   let headers = {};
   let headerList = Array.isArray(headerOption) ? headerOption : [headerOption];
@@ -69,15 +70,14 @@ export function validateApiRequest({
   hasData = false
 }) {
   let errors = [];
-  if (method !== 'GET' && method !== 'POST') {
-    errors.push(`Method ${method} not allowed. Use GET for queries or POST for build comments.`);
-    return errors;
+  if (!API_METHODS.includes(method)) {
+    errors.push(`Unsupported HTTP method: ${method}`);
   }
-  if (method === 'POST' && !isAllowedPostEndpoint(endpoint)) {
-    errors.push(`POST not allowed for ${endpoint}. Only build comment endpoints support POST.`);
+  if (hasData && ['GET', 'HEAD'].includes(method)) {
+    errors.push('Request data requires a method other than GET or HEAD.');
   }
-  if (hasData && method !== 'POST') {
-    errors.push('Request data requires --method POST.');
+  if (/^[a-z][a-z\d+.-]*:/i.test(endpoint) || endpoint.startsWith('//')) {
+    errors.push('Use an API path on the configured Vizzly server.');
   }
   return errors;
 }
@@ -88,7 +88,7 @@ export function buildApiRequest({
   let normalizedEndpoint = normalizeApiEndpoint(endpoint);
   let method = normalizeApiMethod(options.method || 'GET');
   let errors = validateApiRequest({
-    endpoint: normalizedEndpoint,
+    endpoint,
     method,
     hasData: options.data !== undefined
   });
@@ -104,7 +104,7 @@ export function buildApiRequest({
   let requestOptions = {
     method
   };
-  if (options.data && method === 'POST') {
+  if (options.data !== undefined && !['GET', 'HEAD'].includes(method)) {
     headers['Content-Type'] = headers['Content-Type'] || 'application/json';
     requestOptions.body = options.data;
   }
@@ -144,13 +144,24 @@ export async function apiCommand(endpoint, options = {}, globalOptions = {}, dep
     };
     let config = await loadConfig(globalOptions.config, allOptions);
 
-    // Validate API token
-    if (!config.apiKey) {
-      output.error('API token required. Use --token or set VIZZLY_TOKEN environment variable');
+    // A linked project's upload credential must not hide an existing user login.
+    // Explicit file/env/--token credentials still take precedence.
+    let token = config.linkedProject ? config.userToken || config.apiKey : config.apiKey || config.userToken;
+    if (!token && !options.schemaDiscovery) {
+      output.error('Authentication required. Run vizzly login or set VIZZLY_TOKEN.');
       output.cleanup();
       exit(1);
       return;
     }
+    if (options.data?.startsWith('@')) {
+      let source = options.data.slice(1);
+      let data = source === '-' ? await readStdin() : await readFile(source, 'utf8');
+      options = {
+        ...options,
+        data
+      };
+    }
+    if (options.data !== undefined) JSON.parse(options.data);
     let {
       errors,
       method,
@@ -164,10 +175,7 @@ export async function apiCommand(endpoint, options = {}, globalOptions = {}, dep
     displayMethod = method;
     if (errors.length > 0) {
       output.error(errors[0]);
-      if (method === 'POST') {
-        output.hint('Use GET for queries, or use dedicated commands (vizzly approve, vizzly reject, vizzly comment)');
-      }
-      output.hint('Most raw API use should stay read-only; prefer dedicated commands for mutations.');
+      output.hint('Use vizzly api schema to discover supported operations.');
       output.cleanup();
       exit(1);
       return;
@@ -177,10 +185,31 @@ export async function apiCommand(endpoint, options = {}, globalOptions = {}, dep
     output.startSpinner(`${method} ${normalizedEndpoint}`);
     let client = createApiClient({
       baseUrl: config.apiUrl,
-      token: config.apiKey,
-      command: 'api'
+      token,
+      command: 'api',
+      allowNoToken: Boolean(options.schemaDiscovery)
+    });
+    let response = await client.request(normalizedEndpoint, {
+      ...requestOptions,
+      redirect: 'error',
+      retryAuthentication: ['GET', 'HEAD'].includes(method),
+      responseType: options.output ? 'response' : 'json'
     });
-    let response = await client.request(normalizedEndpoint, requestOptions);
+    if (options.output) {
+      let path = resolve(options.output);
+      let file = await open(path, 'wx');
+      try {
+        await pipeline(response.body || Readable.from([]), file.createWriteStream());
+      } catch (error) {
+        await file.close();
+        await unlink(path);
+        throw error;
+      }
+      response = {
+        file: path,
+        contentType: response.headers.get('content-type')
+      };
+    }
     output.stopSpinner();
 
     // Output response
@@ -240,12 +269,30 @@ export function validateApiOptions(endpoint, options = {}) {
   if (!endpoint || endpoint.trim() === '') {
     return errors;
   }
-  let normalizedEndpoint = normalizeApiEndpoint(endpoint);
   let method = normalizeApiMethod(options.method || 'GET');
   errors.push(...validateApiRequest({
-    endpoint: normalizedEndpoint,
+    endpoint,
     method,
     hasData: options.data !== undefined
   }));
   return errors;
+}
+async function readStdin() {
+  let chunks = [];
+  for await (let chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks.map(chunk => Buffer.from(chunk))).toString('utf8');
+}
+export async function apiSchemaCommand(operationId, options, globalOptions) {
+  let endpoint = '/api/sdk/schema';
+  if (operationId) {
+    endpoint += `/${encodeURIComponent(operationId)}`;
+    if (options.full) options = {
+      ...options,
+      query: [...(options.query || []), 'view=full']
+    };
+  } else if (options.full) endpoint += '/openapi';
+  return apiCommand(endpoint, {
+    ...options,
+    schemaDiscovery: true
+  }, globalOptions);
 }

package/dist/commands/init.js

@@ -223,8 +223,10 @@ For user-facing changes, use the repo-local Vizzly skill at
 
 - Inspect existing visual evidence before and after the change.
 - Use the repository's established Vizzly command and owning user workflow.
-- Read bounded JSON with \`--agent --json\`, then inspect baseline, current, and
-  diff images together.
+- For cloud reviews, discover supported requests with
+  \`vizzly api schema --json\` and inspect baseline, current, and diff images
+  together.
+- For local evidence, use \`vizzly context ... --json\`.
 
 Treat Vizzly diffs as review evidence. Do not approve, reject, or replace
 evidence unless the task explicitly asks for that mutation.

package/dist/commands/run.js

@@ -61,19 +61,19 @@ export async function resolveBuildDisplayUrl({
 /**
  * Build the follow-up command for a cloud run.
  *
- * JSON consumers need a self-contained command that returns structured
- * evidence when executed. Human output keeps the existing readable summary.
+ * JSON consumers start with the public schema so they can discover the current
+ * request shape. Human output keeps the readable context summary.
  *
  * @param {string} buildId - Cloud build ID to inspect.
  * @param {Object} options - Command output options.
  * @param {boolean} [options.structured=false] - Include machine-readable JSON.
- * @returns {string} Executable build context command.
+ * @returns {string} Cloud context or schema discovery command.
  */
 function buildContextCommand(buildId, {
   structured = false
 } = {}) {
-  let jsonFlag = structured ? ' --json' : '';
-  return `vizzly context build ${buildId} --agent${jsonFlag} --source cloud`;
+  if (structured) return 'vizzly api schema sdk.getBuildContext --json';
+  return `vizzly context build ${buildId} --source cloud`;
 }
 
 /**

package/dist/commands/status.js

@@ -94,8 +94,8 @@ export function createStatusSuggestedCommands(build = {}) {
     return [];
   }
   return [{
-    label: 'Inspect build context',
-    command: `vizzly --json context build ${build.id} --agent --source cloud`
+    label: 'Discover build context API',
+    command: 'vizzly api schema sdk.getBuildContext --json'
   }, {
     label: 'List comparisons',
     command: `vizzly --json comparisons --build ${build.id}`

package/dist/commands/tdd.js

@@ -31,7 +31,7 @@ function buildLocalContextCommand({
   structured = false
 } = {}) {
   let jsonFlag = structured ? ' --json' : '';
-  return `vizzly context build current --source local --agent${jsonFlag}`;
+  return `vizzly context build current --source local${jsonFlag}`;
 }
 
 /**