@vizzly-testing/cli 0.37.0 → 0.38.0

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/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/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,

package/dist/commands/tdd-screenshots.js

@@ -0,0 +1,417 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { generateScreenshotSignature } from '../tdd/core/signature.js';
+import { TddService as defaultTddService } from '../tdd/tdd-service.js';
+import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
+import * as output from '../utils/output.js';
+import { safePath } from '../utils/security.js';
+let DEFAULT_PAGE_SIZE = 20;
+let MAX_PAGE_SIZE = 100;
+let TDD_SCREENSHOT_STATUSES = new Set(['baseline-created', 'baseline-updated', 'error', 'failed', 'new', 'passed', 'rejected']);
+let TDD_SCREENSHOT_IMAGES = new Set(['current', 'baseline', 'diff', 'all']);
+function readLocalReport(workingDir) {
+  let projectDir = resolve(workingDir);
+  let vizzlyDir = join(projectDir, '.vizzly');
+  let reportPath = join(vizzlyDir, 'report-data.json');
+  if (!existsSync(reportPath)) {
+    return {
+      error: `No local TDD screenshots found. Run "vizzly tdd run <command>" ` + `first. Expected ${reportPath}`
+    };
+  }
+  try {
+    let report = JSON.parse(readFileSync(reportPath, 'utf8'));
+    if (!report || !Array.isArray(report.comparisons)) {
+      return {
+        error: `Local TDD report has no comparisons: ${reportPath}`
+      };
+    }
+    if (report.comparisons.some(comparison => !comparison || typeof comparison !== 'object' || Array.isArray(comparison))) {
+      return {
+        error: `Local TDD report has invalid comparisons: ${reportPath}`
+      };
+    }
+    return {
+      report,
+      projectDir,
+      vizzlyDir
+    };
+  } catch (error) {
+    return {
+      error: `Could not read local TDD report ${reportPath}: ${error.message}`
+    };
+  }
+}
+function resolveImagePath(imageUrl, vizzlyDir) {
+  if (typeof imageUrl !== 'string' || imageUrl.length === 0) return null;
+  let relativePath;
+  if (imageUrl.startsWith('/images/')) {
+    relativePath = imageUrl.slice('/images/'.length);
+  } else if (imageUrl.startsWith('.vizzly/')) {
+    relativePath = imageUrl.slice('.vizzly/'.length);
+  } else {
+    return null;
+  }
+  try {
+    return safePath(vizzlyDir, relativePath);
+  } catch {
+    return null;
+  }
+}
+function readComparisonDetails(vizzlyDir) {
+  let detailsPath = join(vizzlyDir, 'comparison-details.json');
+  if (!existsSync(detailsPath)) return {};
+  try {
+    let details = JSON.parse(readFileSync(detailsPath, 'utf8'));
+    return details && typeof details === 'object' && !Array.isArray(details) ? details : {};
+  } catch {
+    return {};
+  }
+}
+function getViewport(properties) {
+  return {
+    width: properties?.viewport_width ?? properties?.viewport?.width ?? null,
+    height: properties?.viewport_height ?? properties?.viewport?.height ?? null
+  };
+}
+function comparisonSummary(comparison, vizzlyDir) {
+  let currentPath = resolveImagePath(comparison.current, vizzlyDir);
+  return {
+    id: comparison.id,
+    name: comparison.name,
+    status: comparison.status,
+    diffPercentage: comparison.diffPercentage ?? null,
+    browser: comparison.properties?.browser ?? null,
+    viewport: getViewport(comparison.properties),
+    currentImage: currentPath ? {
+      path: currentPath,
+      exists: existsSync(currentPath)
+    } : null
+  };
+}
+function getPaginationOptions(options = {}) {
+  let page = options.page ?? 1;
+  let pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+  let errors = [];
+  if (!Number.isInteger(page) || page < 1) {
+    errors.push('--page must be a positive integer');
+  }
+  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > MAX_PAGE_SIZE) {
+    errors.push(`--page-size must be an integer between 1 and ${MAX_PAGE_SIZE}`);
+  }
+  if (options.status && !TDD_SCREENSHOT_STATUSES.has(options.status)) {
+    errors.push(`--status must be one of: ${[...TDD_SCREENSHOT_STATUSES].join(', ')}`);
+  }
+  return {
+    page,
+    pageSize,
+    errors
+  };
+}
+function reportError(message, commandOutput = output) {
+  commandOutput.error(message);
+  process.exitCode = 1;
+}
+function getImageKinds(image = 'current') {
+  if (!TDD_SCREENSHOT_IMAGES.has(image)) {
+    return {
+      error: `--image must be one of: ${[...TDD_SCREENSHOT_IMAGES].join(', ')}`
+    };
+  }
+  return {
+    kinds: image === 'all' ? ['current', 'baseline', 'diff'] : [image]
+  };
+}
+function imageReferences(comparison, vizzlyDir, kinds) {
+  return Object.fromEntries(kinds.map(kind => {
+    let path = resolveImagePath(comparison[kind], vizzlyDir);
+    return [kind, path ? {
+      path,
+      exists: existsSync(path)
+    } : null];
+  }));
+}
+function readLocalComparison(idOrName, workingDir) {
+  if (!idOrName?.trim()) {
+    return {
+      error: 'A screenshot name or comparison ID is required.'
+    };
+  }
+  let local = readLocalReport(workingDir);
+  if (local.error) return local;
+  let found = findComparison(local.report.comparisons, idOrName);
+  if (found.error) return found;
+  return {
+    local,
+    comparison: found.comparison
+  };
+}
+export function listTddScreenshots(options = {}, workingDir = process.cwd()) {
+  let {
+    page,
+    pageSize,
+    errors
+  } = getPaginationOptions(options);
+  if (errors.length > 0) {
+    reportError(errors.join('\n'));
+    return null;
+  }
+  let local = readLocalReport(workingDir);
+  if (local.error) {
+    reportError(local.error);
+    return null;
+  }
+  let comparisons = options.status ? local.report.comparisons.filter(item => item.status === options.status) : local.report.comparisons;
+  let total = comparisons.length;
+  let totalPages = Math.ceil(total / pageSize);
+  let start = (page - 1) * pageSize;
+  let items = comparisons.slice(start, start + pageSize).map(comparison => comparisonSummary(comparison, local.vizzlyDir));
+  let data = {
+    page,
+    pageSize,
+    total,
+    totalPages,
+    hasPrevious: page > 1 && total > 0,
+    hasNext: start + items.length < total,
+    screenshots: items
+  };
+  if (output.isJson()) {
+    output.data(data);
+    return data;
+  }
+  let pageLabel = totalPages ? ` of ${totalPages}` : '';
+  output.print(`TDD screenshots · ${total} comparison${total === 1 ? '' : 's'} · ` + `page ${page}${pageLabel}`);
+  if (options.status) output.print(`Filtered by status: ${options.status}`);
+  if (items.length === 0) {
+    output.print('No screenshots on this page.');
+  }
+  for (let [index, item] of items.entries()) {
+    let row = start + index + 1;
+    let diff = !Number.isFinite(item.diffPercentage) ? '' : ` · ${item.diffPercentage.toFixed(2)}% diff`;
+    output.print(`${row}. ${item.status} · ${item.name} · ${item.id}${diff}`);
+  }
+  if (data.hasNext) {
+    output.blank();
+    let nextPageCommand = `Next page: vizzly tdd screenshots list --page ${page + 1} ` + `--page-size ${pageSize}`;
+    if (options.status) nextPageCommand += ` --status ${options.status}`;
+    output.print(nextPageCommand);
+  }
+  if (items.length > 0) {
+    output.blank();
+    output.print('Inspect one: vizzly tdd screenshots show <id>');
+  }
+  return data;
+}
+export function latestTddScreenshot(name = null, workingDir = process.cwd()) {
+  let local = readLocalReport(workingDir);
+  if (local.error) {
+    reportError(local.error);
+    return null;
+  }
+  let matches = local.report.comparisons.map((comparison, index) => ({
+    comparison,
+    index
+  })).filter(({
+    comparison
+  }) => !name || comparison.name === name).sort((left, right) => {
+    let leftTimestamp = Number(left.comparison.timestamp) || 0;
+    let rightTimestamp = Number(right.comparison.timestamp) || 0;
+    return rightTimestamp - leftTimestamp || right.index - left.index;
+  });
+  if (matches.length === 0) {
+    reportError(name ? `No local TDD screenshot found for "${name}".` : 'No local TDD screenshots were captured.');
+    return null;
+  }
+  let {
+    comparison
+  } = matches[0];
+  let image = imageReferences(comparison, local.vizzlyDir, ['current']).current;
+  let data = {
+    id: comparison.id,
+    name: comparison.name,
+    status: comparison.status,
+    timestamp: comparison.timestamp ?? null,
+    image
+  };
+  if (!image?.exists) {
+    reportError(`The latest screenshot is missing for "${comparison.name}".`);
+    return null;
+  }
+  if (output.isJson()) {
+    output.data(data);
+    return data;
+  }
+  output.print(image.path);
+  return data;
+}
+function findComparison(comparisons, idOrName) {
+  let byId = comparisons.find(item => item.id === idOrName);
+  if (byId) return {
+    comparison: byId
+  };
+  let bySignature = comparisons.find(item => item.signature === idOrName);
+  if (bySignature) return {
+    comparison: bySignature
+  };
+  let byName = comparisons.filter(item => item.name === idOrName);
+  if (byName.length === 1) return {
+    comparison: byName[0]
+  };
+  if (byName.length > 1) {
+    return {
+      error: `More than one screenshot is named "${idOrName}". ` + `Use a comparison ID: ${byName.map(item => item.id).join(', ')}`
+    };
+  }
+  let prefixMatches = comparisons.filter(item => String(item.id || '').startsWith(idOrName));
+  if (prefixMatches.length === 1) return {
+    comparison: prefixMatches[0]
+  };
+  if (prefixMatches.length > 1) {
+    return {
+      error: `Comparison ID prefix "${idOrName}" is ambiguous. Use a full ID.`
+    };
+  }
+  return {
+    error: `No local TDD screenshot found for "${idOrName}".`
+  };
+}
+export function showTddScreenshot(idOrName, options = {}, workingDir = process.cwd()) {
+  let selected = readLocalComparison(idOrName, workingDir);
+  if (selected.error) {
+    reportError(selected.error);
+    return null;
+  }
+  let {
+    kinds,
+    error
+  } = getImageKinds(options.image);
+  if (error) {
+    reportError(error);
+    return null;
+  }
+  let {
+    local,
+    comparison
+  } = selected;
+  let comparisonFacts = {
+    ...comparison
+  };
+  delete comparisonFacts.baseline;
+  delete comparisonFacts.current;
+  delete comparisonFacts.diff;
+  let detail = {
+    comparison: comparisonFacts,
+    images: imageReferences(comparison, local.vizzlyDir, kinds),
+    details: readComparisonDetails(local.vizzlyDir)[comparison.id] || {}
+  };
+  if (output.isJson()) {
+    output.data(detail);
+    return detail;
+  }
+  let {
+    properties = {}
+  } = comparison;
+  let viewport = getViewport(properties);
+  output.print(`${comparison.name} · ${comparison.status}`);
+  output.print(`ID: ${comparison.id}`);
+  if (comparison.signature) output.print(`Signature: ${comparison.signature}`);
+  if (Number.isFinite(comparison.diffPercentage)) {
+    output.print(`Difference: ${comparison.diffPercentage.toFixed(2)}%`);
+  }
+  if (properties.browser) output.print(`Browser: ${properties.browser}`);
+  if (viewport.width && viewport.height) {
+    output.print(`Viewport: ${viewport.width}×${viewport.height}`);
+  }
+  if (comparison.error) output.print(`Error: ${comparison.error}`);
+  if (comparison.reason) output.print(`Reason: ${comparison.reason}`);
+  for (let kind of kinds) {
+    let image = detail.images[kind];
+    let imageLabel = image ? `${image.path}${image.exists ? '' : ' (missing)'}` : 'not available';
+    output.print(`${kind}: ${imageLabel}`);
+  }
+  return detail;
+}
+function removeComparisonDetails(comparison, vizzlyDir, writeFile) {
+  let detailsPath = join(vizzlyDir, 'comparison-details.json');
+  if (!existsSync(detailsPath)) return;
+  let details;
+  try {
+    details = JSON.parse(readFileSync(detailsPath, 'utf8'));
+  } catch {
+    return;
+  }
+  if (!details || typeof details !== 'object' || Array.isArray(details) || !Object.hasOwn(details, comparison.id)) {
+    return;
+  }
+  delete details[comparison.id];
+  writeFile(detailsPath, JSON.stringify(details));
+}
+function updateReportAfterAccept(report, comparison, baselinePath) {
+  let timestamp = Date.now();
+  let updatedComparison = {
+    ...comparison,
+    status: 'passed',
+    baseline: baselinePath ? `/images/baselines/${basename(baselinePath)}` : comparison.baseline,
+    diffPercentage: 0,
+    diff: null
+  };
+  let comparisons = report.comparisons.map(item => item.id === comparison.id ? {
+    ...updatedComparison,
+    initialStatus: item.initialStatus || item.status
+  } : item);
+  return {
+    ...report,
+    timestamp,
+    comparisons,
+    summary: {
+      total: comparisons.length,
+      passed: comparisons.filter(item => ['passed', 'baseline-created', 'new'].includes(item.status)).length,
+      failed: comparisons.filter(item => item.status === 'failed').length,
+      rejected: comparisons.filter(item => item.status === 'rejected').length,
+      errors: comparisons.filter(item => item.status === 'error').length
+    }
+  };
+}
+export async function acceptTddScreenshot(idOrName, workingDir = process.cwd(), deps = {}) {
+  let {
+    loadConfig = defaultLoadConfig,
+    TddService = defaultTddService,
+    writeFile = writeFileSync,
+    output: commandOutput = output
+  } = deps;
+  let selected = readLocalComparison(idOrName, workingDir);
+  if (selected.error) {
+    reportError(selected.error, commandOutput);
+    return null;
+  }
+  let {
+    local,
+    comparison
+  } = selected;
+  try {
+    let config = await loadConfig();
+    let service = new TddService(config, local.projectDir);
+    await service.loadBaseline();
+    let accepted = await service.acceptBaseline(comparison);
+    let signature = generateScreenshotSignature(comparison.name, comparison.properties || {}, service.signatureProperties);
+    let baseline = service.baselineData?.screenshots?.find(item => item.signature === signature);
+    writeFile(join(local.vizzlyDir, 'report-data.json'), JSON.stringify(updateReportAfterAccept(local.report, comparison, baseline?.path)));
+    removeComparisonDetails(comparison, local.vizzlyDir, writeFile);
+    let data = {
+      id: comparison.id,
+      name: comparison.name,
+      status: accepted.status,
+      baseline: baseline?.path ?? null
+    };
+    if (commandOutput.isJson()) {
+      commandOutput.data(data);
+    } else {
+      commandOutput.success(`Accepted ${comparison.name} as the local baseline`, {
+        baseline: data.baseline
+      });
+    }
+    return data;
+  } catch (error) {
+    reportError(`Failed to accept ${comparison.name}: ${error.message}`, commandOutput);
+    return null;
+  }
+}

package/dist/commands/tdd.js

@@ -14,7 +14,7 @@ import { createConfigService as defaultCreateConfigService } from '../services/c
 import { createProjectService as defaultCreateProjectService } from '../services/project-service.js';
 import { initializeDaemon as defaultInitializeDaemon, runTests as defaultRunTests } from '../test-runner/index.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';
 
 /**
@@ -58,6 +58,7 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
     runTests = defaultRunTests,
     detectBranch = defaultDetectBranch,
     detectCommit = defaultDetectCommit,
+    detectCommitAuthor = defaultDetectCommitAuthor,
     detectCommitMessage = defaultDetectCommitMessage,
     detectPullRequestNumber = defaultDetectPullRequestNumber,
     generateBuildNameWithGit = defaultGenerateBuildNameWithGit,
@@ -107,6 +108,7 @@ export async function tddCommand(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();
 
@@ -160,6 +162,8 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {},
       branch,
       commit,
       message,
+      commitAuthorName: commitAuthor.name,
+      commitAuthorEmail: commitAuthor.email,
       environment: config.build.environment,
       pullRequestNumber,
       parallelId: config.parallelId,

package/dist/commands/upload.js

@@ -3,7 +3,7 @@ import { CONFIG_DEFAULTS } from '../config/core.js';
 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';
 
@@ -59,6 +59,7 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
     createUploader = defaultCreateUploader,
     detectBranch = defaultDetectBranch,
     detectCommit = defaultDetectCommit,
+    detectCommitAuthor = defaultDetectCommitAuthor,
     detectCommitMessage = defaultDetectCommitMessage,
     detectPullRequestNumber = defaultDetectPullRequestNumber,
     generateBuildNameWithGit = defaultGenerateBuildNameWithGit,
@@ -100,6 +101,7 @@ export async function uploadCommand(screenshotsPath, 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();
     output.info(`Uploading screenshots from: ${screenshotsPath}`);
@@ -127,6 +129,8 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
       branch,
       commit,
       message,
+      commitAuthorName: commitAuthor.name,
+      commitAuthorEmail: commitAuthor.email,
       environment: config.build.environment,
       threshold: config.comparison.threshold,
       minClusterSize: config.comparison.minClusterSize,

package/dist/test-runner/core.js

@@ -64,6 +64,8 @@ export function buildApiBuildPayload(options, comparisonConfig = null) {
     environment: options.environment || 'test',
     commit_sha: options.commit,
     commit_message: options.message,
+    commit_author_name: options.commitAuthorName,
+    commit_author_email: options.commitAuthorEmail,
     github_pull_request_number: options.pullRequestNumber,
     parallel_id: options.parallelId
   };

package/dist/types/index.d.ts

@@ -165,6 +165,8 @@ export interface UploadOptions {
   branch?: string;
   commit?: string;
   message?: string;
+  commitAuthorName?: string;
+  commitAuthorEmail?: string;
   environment?: string;
   threshold?: number;
   minClusterSize?: number;
@@ -517,6 +519,8 @@ export interface BuildOptions {
   commit_sha?: string;
   message?: string;
   commit_message?: string;
+  commitAuthorName?: string;
+  commitAuthorEmail?: string;
   environment?: string;
   threshold?: number;
   eager?: boolean;

package/dist/uploader/core.js

@@ -154,6 +154,8 @@ export function buildBuildInfo(options, defaultBranch = 'main') {
     branch: options.branch || defaultBranch || 'main',
     commit_sha: options.commit,
     commit_message: options.message,
+    commit_author_name: options.commitAuthorName,
+    commit_author_email: options.commitAuthorEmail,
     environment: options.environment || 'production',
     threshold: options.threshold,
     github_pull_request_number: options.pullRequestNumber,

package/dist/utils/ci-env.js

@@ -156,13 +156,23 @@ export function getCommit() {
 }
 
 /**
- * Get the commit message from CI environment variables
+ * Get the commit message from CI environment variables.
+ *
+ * For GitHub Actions pull_request events, the checkout is a synthetic merge
+ * commit whose message is "Merge <sha> into <sha>", so the PR title from the
+ * event payload is used instead.
+ *
  * @returns {string|null} Commit message or null if not available
  */
 export function getCommitMessage() {
-  return process.env.VIZZLY_COMMIT_MESSAGE ||
-  // Vizzly override
-  process.env.CI_COMMIT_MESSAGE ||
+  if (process.env.VIZZLY_COMMIT_MESSAGE) {
+    return process.env.VIZZLY_COMMIT_MESSAGE;
+  }
+  if (process.env.GITHUB_ACTIONS) {
+    let title = getGitHubEvent().pull_request?.title;
+    if (title) return title;
+  }
+  return process.env.CI_COMMIT_MESSAGE ||
   // GitLab CI
   process.env.TRAVIS_COMMIT_MESSAGE ||
   // Travis CI
@@ -176,6 +186,35 @@ export function getCommitMessage() {
   // Generic
   null;
 }
+
+/**
+ * Parse a "Name <email>" author string (GitLab's CI_COMMIT_AUTHOR format)
+ * @param {string|undefined} value - Author string
+ * @returns {{ name: string|null, email: string|null }}
+ */
+function parseAuthorString(value) {
+  let match = value?.match(/^(.*?)\s*<([^>]*)>\s*$/);
+  if (!match) return {
+    name: value?.trim() || null,
+    email: null
+  };
+  return {
+    name: match[1] || null,
+    email: match[2] || null
+  };
+}
+
+/**
+ * Get the commit author from CI environment variables
+ * @returns {{ name: string|null, email: string|null }} Author name and email
+ */
+export function getCommitAuthor() {
+  let gitlab = parseAuthorString(process.env.CI_COMMIT_AUTHOR);
+  return {
+    name: process.env.VIZZLY_COMMIT_AUTHOR_NAME || gitlab.name || null,
+    email: process.env.VIZZLY_COMMIT_AUTHOR_EMAIL || gitlab.email || null
+  };
+}
 function parsePullRequestNumber(value) {
   if (!/^\d+$/.test(value)) {
     return null;

package/dist/utils/git.js

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { getBranch as getCIBranch, getCommit as getCICommit, getCommitMessage as getCICommitMessage, getPullRequestNumber } from './ci-env.js';
+import { getBranch as getCIBranch, getCommit as getCICommit, getCommitAuthor as getCICommitAuthor, getCommitMessage as getCICommitMessage, getPullRequestNumber } from './ci-env.js';
 let execFileAsync = promisify(execFile);
 async function runGit(args, cwd = process.cwd()) {
   let {
@@ -124,8 +124,48 @@ export async function detectCommitMessage(override = null, cwd = process.cwd())
   let ciCommitMessage = getCICommitMessage();
   if (ciCommitMessage) return ciCommitMessage;
 
-  // Fallback to regular git log
-  return await getCommitMessage(cwd);
+  // Fallback to git, reading the same commit reported as commit_sha
+  return await readCommit('%B', cwd);
+}
+
+/**
+ * Read a formatted field from the detected build commit.
+ *
+ * Uses detectCommit() so CI checkouts (e.g. GitHub's synthetic PR merge
+ * commit) describe the PR head rather than HEAD. Falls back to HEAD when that
+ * commit is not in local history (shallow clones).
+ *
+ * @param {string} format - git log --format string
+ * @param {string} cwd - Working directory
+ * @returns {Promise<string|null>} Formatted output or null
+ */
+async function readCommit(format, cwd = process.cwd()) {
+  let sha = await detectCommit(null, cwd);
+  let refs = /^[0-9a-f]{4,64}$/i.test(sha || '') ? [sha, 'HEAD'] : ['HEAD'];
+  for (let ref of refs) {
+    try {
+      return await runGit(['log', '-1', `--format=${format}`, ref], cwd);
+    } catch {
+      // Commit not available locally, try the next ref
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect commit author with environment variable support, falling back to git
+ * @param {string} cwd - Working directory
+ * @returns {Promise<{ name: string|null, email: string|null }>}
+ */
+export async function detectCommitAuthor(cwd = process.cwd()) {
+  let author = getCICommitAuthor();
+  if (author.name && author.email) return author;
+  let stdout = await readCommit('%an%x00%ae', cwd);
+  let [gitName, gitEmail] = stdout ? stdout.split('\0') : [];
+  return {
+    name: author.name || gitName || null,
+    email: author.email || gitEmail || null
+  };
 }
 
 /**
@@ -206,9 +246,9 @@ export async function detectCommit(override = null, cwd = process.cwd()) {
  */
 export async function generateBuildNameWithGit(override = null, cwd = process.cwd()) {
   if (override) return override;
-  let branch = await getCurrentBranch(cwd);
-  let shortSha = await getCurrentCommitSha(cwd);
-  if (branch && shortSha) {
+  let branch = await detectBranch(null, cwd);
+  let shortSha = await detectCommit(null, cwd);
+  if (branch && branch !== 'unknown' && shortSha) {
     let shortCommit = shortSha.substring(0, 7);
     return `${branch}-${shortCommit}`;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",

package/skills/vizzly/references/cli-context.md

@@ -86,6 +86,31 @@ vizzly tdd stop --json
 `tdd run` and `tdd start` are alternatives. Stop only a daemon started for the
 current task.
 
+## Review A Local TDD Run
+
+After `tdd run` exits, inspect captures directly from `.vizzly`. These
+commands don't need a running TDD daemon or cloud credentials:
+
+```bash
+vizzly tdd screenshots list --page 1 --page-size 20
+vizzly tdd screenshots latest
+vizzly tdd screenshots show <comparison-id>
+```
+
+`latest` prints the current screenshot path for the most recent capture. Use
+`list` to find a comparison ID when you need a specific screenshot or browser
+variant. During UI iteration, inspect the current image first; request
+`--image diff` or `--image all` when comparison diagnostics help answer the
+question. Open the printed image paths with the available image viewer.
+
+`accept` replaces one local baseline and updates that report entry. Use it only
+when the task explicitly authorizes accepting a baseline; don't accept a change
+just to make a diff disappear:
+
+```bash
+vizzly tdd screenshots accept <comparison-id>
+```
+
 When a cloud build is in scope:
 
 ```bash