@vizzly-testing/cli 0.37.0 → 0.38.1

package/README.md

@@ -20,7 +20,7 @@ build or diff data for scripts, automation, and coding agents.
 
 ## Quick Start
 
-You need Node.js 22+.
+You need Node.js 22.18 or newer within Node 22, or Node.js 24+.
 
 ```bash
 pnpm install -g @vizzly-testing/cli
@@ -43,6 +43,19 @@ existing Vizzly config.
 Use `vizzly init --agent-skill` to install or refresh only the local skill, or
 `vizzly init --skip-agent-skill` when you want config without the agent prompt.
 
+### TypeScript Configuration
+
+Vizzly loads `vizzly.config.ts` with Node's native type stripping. Type
+annotations, interfaces, and `satisfies` work without installing TypeScript.
+Use `import type` for type-only imports and include file extensions when
+importing local helpers, such as `./helpers.ts`.
+
+Enums, namespaces containing runtime code, and constructor parameter properties
+aren't supported. Replace them with ordinary JavaScript values and assignments.
+Node doesn't apply `tsconfig.json` path aliases when loading your config.
+These restrictions apply to the config and its imports; they don't change how
+your application or tests compile.
+
 ### Start Local TDD
 
 Start the TDD server, run your tests, and open the dashboard at the URL the

package/dist/api/core.js

@@ -126,6 +126,12 @@ export function buildBuildPayload(options) {
   if (options.message || options.commit_message) {
     payload.commit_message = options.message || options.commit_message;
   }
+  if (options.commit_author_name) {
+    payload.commit_author_name = options.commit_author_name;
+  }
+  if (options.commit_author_email) {
+    payload.commit_author_email = options.commit_author_email;
+  }
   if (options.pullRequestNumber || options.github_pull_request_number) {
     payload.github_pull_request_number = options.pullRequestNumber || options.github_pull_request_number;
   }

package/dist/auth/client.js

@@ -56,7 +56,10 @@ export function createAuthClient(options = {}) {
     });
     if (!response.ok) {
       let body = await parseResponseBody(response);
-      throw parseAuthError(response.status, body, endpoint);
+      let error = parseAuthError(response.status, body, endpoint);
+      let retryAfter = Number(response.headers?.get('retry-after'));
+      if (retryAfter > 0) error.context.retryAfter = retryAfter;
+      throw error;
     }
     return response.json();
   }

package/dist/auth/core.js

@@ -70,13 +70,19 @@ export function parseAuthError(status, body, _endpoint) {
   } else if (typeof body === 'string') {
     errorText = body;
   }
+  let retryAfter = Number(body?.retryAfter);
+  let context = {
+    status,
+    serverCode: body?.code,
+    retryAfter: retryAfter > 0 ? retryAfter : undefined
+  };
   if (status === 401) {
-    return new AuthError(errorText || 'Invalid credentials. Please check your email/username and password.');
+    return new AuthError(errorText || 'Invalid credentials. Please check your email/username and password.', context);
   }
   if (status === 429) {
-    return new VizzlyError('Too many login attempts. Please try again later.', 'RATE_LIMIT_ERROR');
+    return new VizzlyError('Too many login attempts. Please try again later.', 'RATE_LIMIT_ERROR', context);
   }
-  return new VizzlyError(`Authentication request failed: ${status}${errorText ? ` - ${errorText}` : ''}`, 'AUTH_REQUEST_ERROR');
+  return new VizzlyError(`Authentication request failed: ${status}${errorText ? ` - ${errorText}` : ''}`, 'AUTH_REQUEST_ERROR', context);
 }
 
 /**
@@ -173,4 +179,59 @@ export function validateTokens(auth, requiredField = 'accessToken') {
     valid: true,
     error: null
   };
+}
+export function normalizeDeviceFlowResponse(deviceFlow) {
+  let verificationUri = deviceFlow.verification_uri || deviceFlow.verificationUri;
+  let userCode = deviceFlow.user_code || deviceFlow.userCode;
+  let deviceCode = deviceFlow.device_code || deviceFlow.deviceCode;
+  if (!verificationUri || !userCode || !deviceCode) {
+    throw new Error('Invalid device flow response from server');
+  }
+  return {
+    verificationUri,
+    userCode,
+    deviceCode,
+    urlWithCode: deviceFlow.verification_uri_complete || deviceFlow.verificationUriComplete || `${verificationUri}?code=${encodeURIComponent(userCode)}`
+  };
+}
+export function resolveAuthorizedTokenData(pollResponse) {
+  let accessToken = pollResponse.tokens?.accessToken || pollResponse.tokens?.access_token;
+  if (accessToken) {
+    return pollResponse;
+  }
+  if (pollResponse.status === 'pending') {
+    throw new Error('Authorization not complete yet. Please complete the authorization in your browser and try running "vizzly login" again.');
+  }
+  if (pollResponse.status === 'expired') {
+    throw new Error('Device code expired. Please try logging in again.');
+  }
+  if (pollResponse.status === 'invalid') {
+    throw new Error('Device code is invalid or expired. Please try logging in again.');
+  }
+  if (pollResponse.status === 'denied') {
+    throw new Error('Authorization denied. Please try logging in again.');
+  }
+  throw new Error('Unexpected response from authorization server. Please try logging in again.');
+}
+export function buildTokens(tokenData, now = Date.now()) {
+  let tokensData = tokenData.tokens || tokenData;
+  let tokenExpiresIn = tokensData.expiresIn || tokensData.expires_in;
+  let tokenExpiresAt = tokenExpiresIn ? new Date(now + tokenExpiresIn * 1000).toISOString() : tokenData.expires_at || tokenData.expiresAt;
+  return {
+    accessToken: tokensData.accessToken || tokensData.access_token,
+    refreshToken: tokensData.refreshToken || tokensData.refresh_token,
+    expiresAt: tokenExpiresAt,
+    user: tokenData.user,
+    organizations: tokenData.organizations
+  };
+}
+
+/** Map protocol codes without depending on the server's human-readable text. */
+export function deviceAuthorizationStatus(error) {
+  return {
+    AUTHORIZATION_PENDING: 'pending',
+    ACCESS_DENIED: 'denied',
+    EXPIRED_TOKEN: 'expired',
+    INVALID_DEVICE_CODE: 'invalid'
+  }[error.context?.serverCode];
 }

package/dist/auth/operations.js

@@ -8,7 +8,8 @@
  * This makes them trivially testable without mocking modules.
  */
 
-import { buildDevicePollPayload, buildLogoutPayload, buildRefreshPayload, buildTokenData, validateTokens } from './core.js';
+import * as output from '../utils/output.js';
+import { buildDevicePollPayload, buildLogoutPayload, buildRefreshPayload, buildTokenData, deviceAuthorizationStatus, validateTokens } from './core.js';
 
 // ============================================================================
 // Device Flow Operations
@@ -34,14 +35,23 @@ export async function initiateDeviceFlow(httpClient) {
  * @param {string} deviceCode - Device code from initiate
  * @returns {Promise<Object>} Token data or pending status
  */
-export async function pollDeviceAuthorization(httpClient, deviceCode) {
-  return httpClient.request('/api/auth/cli/device/poll', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify(buildDevicePollPayload(deviceCode))
-  });
+export async function pollDeviceAuthorization(httpClient, deviceCode, options = {}) {
+  try {
+    return await httpClient.request('/api/auth/cli/device/poll', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(buildDevicePollPayload(deviceCode)),
+      signal: options.signal
+    });
+  } catch (error) {
+    let status = deviceAuthorizationStatus(error);
+    if (status) return {
+      status
+    };
+    throw error;
+  }
 }
 
 /**
@@ -98,7 +108,7 @@ export async function logout(httpClient, tokenStore) {
   let auth = await tokenStore.getTokens();
   if (auth?.refreshToken) {
     try {
-      await httpClient.request('/api/auth/cli/logout', {
+      await httpClient.authenticatedRequest('/api/auth/cli/logout', auth.accessToken, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json'
@@ -107,7 +117,7 @@ export async function logout(httpClient, tokenStore) {
       });
     } catch (error) {
       // If server request fails, still clear local tokens
-      console.warn('Warning: Failed to revoke tokens on server:', error.message);
+      output.warn(`Failed to revoke tokens on server: ${error.message}`);
     }
   }
   await tokenStore.clearTokens();

package/dist/cli.js

@@ -22,6 +22,7 @@ import { runCommand, validateRunOptions } from './commands/run.js';
 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 { acceptTddScreenshot, latestTddScreenshot, listTddScreenshots, showTddScreenshot } from './commands/tdd-screenshots.js';
 import { uploadCommand, validateUploadOptions } from './commands/upload.js';
 import { whoamiCommand } from './commands/whoami.js';
 import { createPluginServices } from './plugin-api.js';
@@ -528,6 +529,19 @@ tddCmd.command('list').description('List all running TDD servers').action(async
   let globalOptions = getGlobalOptions();
   await tddListCommand(options, globalOptions);
 });
+let tddScreenshotsCmd = tddCmd.command('screenshots').description('Browse local TDD screenshots without a server');
+tddScreenshotsCmd.command('list').description('List captured screenshots from the latest local TDD run').option('--page <number>', 'Page number', Number, 1).option('--page-size <number>', 'Screenshots per page (max 100)', Number, 20).option('--status <status>', 'Filter by comparison status').action(options => {
+  listTddScreenshots(options);
+});
+tddScreenshotsCmd.command('latest [name]').description('Print the latest captured screenshot path').action(name => {
+  latestTddScreenshot(name);
+});
+tddScreenshotsCmd.command('show <id-or-name>').description('Inspect a screenshot; print current image by default').option('--image <kind>', 'Print image path: current, baseline, diff, or all', 'current').action((idOrName, options) => {
+  showTddScreenshot(idOrName, options);
+});
+tddScreenshotsCmd.command('accept <id-or-name>').description('Accept a captured screenshot as its new local baseline').action(async idOrName => {
+  await acceptTddScreenshot(idOrName);
+});
 
 // TDD Run - One-off test run with ephemeral server (generates static report)
 tddCmd.command('run <command>').description('Run tests once in TDD mode with local visual review').option('--port <port>', 'Port for TDD server').option('--branch <branch>', 'Git branch override').option('--environment <env>', 'Environment name', 'test').option('--threshold <number>', 'Comparison threshold', Number).option('--min-cluster-size <pixels>', 'Minimum changed-pixel cluster size', Number).option('--token <token>', 'API token override').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--baseline-build <id>', 'Use specific build as baseline').option('--baseline-comparison <id>', 'Use specific comparison as baseline').option('--set-baseline', 'Accept current screenshots as new baseline (overwrites existing)').option('--fail-on-diff', 'Fail tests when visual differences are detected').option('--no-open', 'Skip opening report in browser').action(async (command, options) => {

package/dist/commands/login.js

@@ -3,110 +3,13 @@
  * Authenticates user via OAuth device flow
  */
 
+import { setTimeout as delay } from 'node:timers/promises';
+import { buildTokens, normalizeDeviceFlowResponse, resolveAuthorizedTokenData } from '../auth/core.js';
 import { completeDeviceFlow, createAuthClient, createTokenStore, initiateDeviceFlow, pollDeviceAuthorization } from '../auth/index.js';
 import { openBrowser } from '../utils/browser.js';
 import { getApiUrl } from '../utils/environment-config.js';
+import { waitForLoginPoll } from '../utils/login-poll-wait.js';
 import * as output from '../utils/output.js';
-function createLoginDeps(deps = {}) {
-  return {
-    completeDeviceFlow: deps.completeDeviceFlow || completeDeviceFlow,
-    createAuthClient: deps.createAuthClient || createAuthClient,
-    createTokenStore: deps.createTokenStore || createTokenStore,
-    getApiUrl: deps.getApiUrl || getApiUrl,
-    initiateDeviceFlow: deps.initiateDeviceFlow || initiateDeviceFlow,
-    now: deps.now || (() => Date.now()),
-    openBrowser: deps.openBrowser || openBrowser,
-    output: deps.output || output,
-    pollDeviceAuthorization: deps.pollDeviceAuthorization || pollDeviceAuthorization,
-    waitForEnter: deps.waitForEnter || waitForEnter,
-    exit: deps.exit || (code => process.exit(code))
-  };
-}
-function configureOutput(output, globalOptions) {
-  output.configure({
-    json: globalOptions.json,
-    verbose: globalOptions.verbose,
-    color: !globalOptions.noColor
-  });
-}
-export function normalizeDeviceFlowResponse(deviceFlow) {
-  let verificationUri = deviceFlow.verification_uri || deviceFlow.verificationUri;
-  let userCode = deviceFlow.user_code || deviceFlow.userCode;
-  let deviceCode = deviceFlow.device_code || deviceFlow.deviceCode;
-  if (!verificationUri || !userCode || !deviceCode) {
-    throw new Error('Invalid device flow response from server');
-  }
-  return {
-    verificationUri,
-    userCode,
-    deviceCode,
-    urlWithCode: `${verificationUri}?code=${encodeURIComponent(userCode)}`
-  };
-}
-export function resolveAuthorizedTokenData(pollResponse) {
-  let accessToken = pollResponse.tokens?.accessToken || pollResponse.tokens?.access_token;
-  if (accessToken) {
-    return pollResponse;
-  }
-  if (pollResponse.status === 'pending') {
-    throw new Error('Authorization not complete yet. Please complete the authorization in your browser and try running "vizzly login" again.');
-  }
-  if (pollResponse.status === 'expired') {
-    throw new Error('Device code expired. Please try logging in again.');
-  }
-  if (pollResponse.status === 'denied') {
-    throw new Error('Authorization denied. Please try logging in again.');
-  }
-  throw new Error('Unexpected response from authorization server. Please try logging in again.');
-}
-export function buildTokens(tokenData, now = Date.now()) {
-  let tokensData = tokenData.tokens || tokenData;
-  let tokenExpiresIn = tokensData.expiresIn || tokensData.expires_in;
-  let tokenExpiresAt = tokenExpiresIn ? new Date(now + tokenExpiresIn * 1000).toISOString() : tokenData.expires_at || tokenData.expiresAt;
-  return {
-    accessToken: tokensData.accessToken || tokensData.access_token,
-    refreshToken: tokensData.refreshToken || tokensData.refresh_token,
-    expiresAt: tokenExpiresAt,
-    user: tokenData.user,
-    organizations: tokenData.organizations
-  };
-}
-export function getTokenExpiryHint(expiresAt, now = Date.now()) {
-  if (!expiresAt) {
-    return null;
-  }
-  let expiry = new Date(expiresAt);
-  let msUntilExpiry = expiry.getTime() - now;
-  let daysUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60 * 60 * 24));
-  let hoursUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60 * 60));
-  let minutesUntilExpiry = Math.floor(msUntilExpiry / (1000 * 60));
-  if (daysUntilExpiry > 0) {
-    return `Token expires in ${daysUntilExpiry} day${daysUntilExpiry !== 1 ? 's' : ''}`;
-  }
-  if (hoursUntilExpiry > 0) {
-    return `Token expires in ${hoursUntilExpiry} hour${hoursUntilExpiry !== 1 ? 's' : ''}`;
-  }
-  if (minutesUntilExpiry > 0) {
-    return `Token expires in ${minutesUntilExpiry} minute${minutesUntilExpiry !== 1 ? 's' : ''}`;
-  }
-  return null;
-}
-export async function waitForEnter(stdin = process.stdin) {
-  await new Promise(resolve => {
-    let canSetRawMode = typeof stdin.setRawMode === 'function';
-    if (canSetRawMode) {
-      stdin.setRawMode(true);
-    }
-    stdin.resume();
-    stdin.once('data', () => {
-      if (canSetRawMode) {
-        stdin.setRawMode(false);
-      }
-      stdin.pause();
-      resolve();
-    });
-  });
-}
 
 /**
  * Login command implementation using OAuth device flow
@@ -115,19 +18,14 @@ export async function waitForEnter(stdin = process.stdin) {
  */
 export async function loginCommand(options = {}, globalOptions = {}, deps = {}) {
   let {
-    completeDeviceFlow,
-    createAuthClient,
-    createTokenStore,
-    getApiUrl,
-    initiateDeviceFlow,
-    now,
-    openBrowser,
-    output,
-    pollDeviceAuthorization,
-    waitForEnter,
-    exit
-  } = createLoginDeps(deps);
-  configureOutput(output, globalOptions);
+    now = Date.now,
+    delay: sleep = delay
+  } = deps;
+  output.configure({
+    json: globalOptions.json,
+    verbose: globalOptions.verbose,
+    color: !globalOptions.noColor
+  });
   let colors = output.getColors();
   try {
     output.header('login');
@@ -142,6 +40,12 @@ export async function loginCommand(options = {}, globalOptions = {}, deps = {})
     output.startSpinner('Connecting to Vizzly...');
     let deviceFlow = await initiateDeviceFlow(client);
     output.stopSpinner();
+    let expiresIn = Number(deviceFlow.expires_in ?? deviceFlow.expiresIn);
+    let lifetime = Number.isFinite(expiresIn) && expiresIn > 0 ? Math.min(expiresIn, 120) : 120;
+    let deadline = now() + lifetime * 1000;
+    let timeoutMessage = expiresIn > 0 && expiresIn <= 120 ? 'Device code expired. Please try logging in again.' : 'Login timed out after 2 minutes. Please try logging in again.';
+    let interval = Number(deviceFlow.interval);
+    let pollDelay = Number.isFinite(interval) && interval > 0 ? interval * 1000 : 5000;
 
     // Handle both snake_case and camelCase field names
     let {
@@ -166,14 +70,57 @@ export async function loginCommand(options = {}, globalOptions = {}, deps = {})
       output.hint('Please open the URL manually');
     }
     output.blank();
-    output.hint('After authorizing, press Enter to continue...');
-
-    // Wait for user to press Enter
-    await waitForEnter();
-
-    // Check authorization status
-    output.startSpinner('Checking authorization...');
-    let pollResponse = await pollDeviceAuthorization(client, deviceCode);
+    output.hint('Waiting for authorization in your browser (up to 2 minutes)...');
+    let interactive = process.stdin.isTTY && !globalOptions.json;
+    let backoff = false;
+    let lastCheckAt = 0;
+    let pollResponse;
+    while (true) {
+      let remaining = deadline - now();
+      if (remaining <= 0) {
+        throw new Error(timeoutMessage);
+      }
+      await waitForLoginPoll({
+        milliseconds: Math.min(pollDelay, remaining),
+        manualAllowed: !backoff,
+        earliestCheckAt: lastCheckAt + 1000,
+        stdin: interactive ? process.stdin : {
+          isTTY: false
+        },
+        now,
+        sleep,
+        onTick: (milliseconds, canCheck) => {
+          let seconds = Math.ceil(milliseconds / 1000);
+          let message = backoff ? `Rate limited. Next check in ${seconds}s` : `Next check in ${seconds}s`;
+          if (canCheck) message += ' — press Enter to check now';
+          if (interactive) output.updateSpinner(message);else output.hint(message);
+        }
+      });
+      remaining = deadline - now();
+      if (remaining <= 0) {
+        throw new Error(timeoutMessage);
+      }
+      lastCheckAt = now();
+      output.updateSpinner('Checking authorization...');
+      try {
+        pollResponse = await pollDeviceAuthorization(client, deviceCode, {
+          signal: AbortSignal.timeout(Math.ceil(Math.min(remaining, 30000)))
+        });
+      } catch (error) {
+        if (now() >= deadline) {
+          throw new Error(timeoutMessage);
+        }
+        if (error.code !== 'RATE_LIMIT_ERROR') throw error;
+        backoff = true;
+        let retryAfter = Number(error.context?.retryAfter);
+        if (Number.isFinite(retryAfter) && retryAfter > 0) {
+          pollDelay = Math.max(pollDelay, retryAfter * 1000);
+        }
+        continue;
+      }
+      backoff = false;
+      if (pollResponse.status !== 'pending') break;
+    }
     output.stopSpinner();
     let tokenData = resolveAuthorizedTokenData(pollResponse);
 
@@ -201,17 +148,8 @@ export async function loginCommand(options = {}, globalOptions = {}, deps = {})
       let orgItems = tokens.organizations.map(org => `${org.name}${org.slug ? ` (@${org.slug})` : ''}`);
       output.list(orgItems);
     }
-
-    // Show token expiry info
-    if (tokens.expiresAt) {
-      output.blank();
-      let expiryHint = getTokenExpiryHint(tokens.expiresAt, now());
-      if (expiryHint) {
-        output.hint(expiryHint);
-      }
-    }
     output.blank();
-    output.hint('Run "vizzly project link <org>/<project>" to enable cloud uploads');
+    output.hint('You can now browse cloud builds and download baselines');
     output.cleanup();
   } catch (error) {
     output.stopSpinner();
@@ -222,18 +160,14 @@ export async function loginCommand(options = {}, globalOptions = {}, deps = {})
       output.blank();
       output.hint('Please try logging in again');
       output.hint("If you don't have an account, sign up at https://vizzly.dev");
-      output.cleanup();
-      exit(1);
     } else if (error.code === 'RATE_LIMIT_ERROR') {
       output.error('Too many login attempts', error);
       output.blank();
       output.hint('Please wait a few minutes before trying again');
-      output.cleanup();
-      exit(1);
     } else {
       output.error('Login failed', error);
-      output.cleanup();
-      exit(1);
     }
+    output.cleanup();
+    process.exit(1);
   }
 }

package/dist/commands/run.js

@@ -18,7 +18,7 @@ import { finalizeBuild as defaultFinalizeBuild, runTests as defaultRunTests } fr
 import { createUploader as defaultCreateUploader } from '../uploader/index.js';
 import { getAppBaseUrl } from '../utils/api-url.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
-import { detectBranch as defaultDetectBranch, detectCommit as defaultDetectCommit, detectCommitMessage as defaultDetectCommitMessage, detectPullRequestNumber as defaultDetectPullRequestNumber, generateBuildNameWithGit as defaultGenerateBuildNameWithGit } from '../utils/git.js';
+import { detectBranch as defaultDetectBranch, detectCommit as defaultDetectCommit, detectCommitAuthor as defaultDetectCommitAuthor, detectCommitMessage as defaultDetectCommitMessage, detectPullRequestNumber as defaultDetectPullRequestNumber, generateBuildNameWithGit as defaultGenerateBuildNameWithGit } from '../utils/git.js';
 import * as defaultOutput from '../utils/output.js';
 import { writeSession as defaultWriteSession } from '../utils/session.js';
 function formatUploadCounts({
@@ -100,6 +100,7 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
     runTests = defaultRunTests,
     detectBranch = defaultDetectBranch,
     detectCommit = defaultDetectCommit,
+    detectCommitAuthor = defaultDetectCommitAuthor,
     detectCommitMessage = defaultDetectCommitMessage,
     detectPullRequestNumber = defaultDetectPullRequestNumber,
     generateBuildNameWithGit = defaultGenerateBuildNameWithGit,
@@ -210,6 +211,7 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
     let branch = await detectBranch(options.branch || config.build.branch);
     let commit = await detectCommit(options.commit || config.build.commit);
     let message = options.message || config.build.message || (await detectCommitMessage());
+    let commitAuthor = await detectCommitAuthor();
     let buildName = await generateBuildNameWithGit(options.buildName || configuredBuildName);
     let pullRequestNumber = detectPullRequestNumber();
     if (globalOptions.verbose) {
@@ -269,6 +271,8 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
       branch,
       commit,
       message,
+      commitAuthorName: commitAuthor.name,
+      commitAuthorEmail: commitAuthor.email,
       environment: config.build.environment,
       threshold: config.comparison.threshold,
       minClusterSize: config.comparison.minClusterSize,