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

package/dist/server/routers/events.js

@@ -19,7 +19,7 @@ let defaultTimers = {
 /**
  * Read and parse JSON from disk, returning null on missing or invalid files.
  */
-export function readJsonFile(path) {
+function readJsonFile(path) {
   if (!existsSync(path)) {
     return null;
   }
@@ -33,7 +33,7 @@ export function readJsonFile(path) {
 /**
  * Read report data and attach baseline metadata for the stats view.
  */
-export function readReportDataFile({
+function readReportDataFile({
   reportDataPath,
   baselineMetadataPath
 }) {
@@ -84,7 +84,7 @@ function summaryChanged(oldData, newData) {
 /**
  * Build incremental SSE events by diffing old vs new report data.
  */
-export function buildReportDataEvents(oldData, newData) {
+function buildReportDataEvents(oldData, newData) {
   if (!oldData) {
     return [{
       type: 'reportData',
@@ -129,7 +129,7 @@ export function buildReportDataEvents(oldData, newData) {
 /**
  * Watch report-data.json with fs.watch plus a lightweight mtime fallback.
  */
-export function watchReportDataFile({
+function watchReportDataFile({
   workingDir,
   reportDataPath,
   onReportDataChanged,

package/dist/utils/visual-context-normalizers.js

@@ -145,9 +145,11 @@ function getBaselineScreenshot(comparison = {}) {
 /**
  * Project compact Honeydiff facts without making raw geometry the default.
  *
- * Agents need stable counts, fingerprints, URLs, and the API projection for
- * first-pass diagnosis. Raw regions and scoring details stay behind an
- * explicit include because they can dominate an otherwise bounded handoff.
+ * Agents need stable counts, fingerprints, URLs, the API projection, and the
+ * server's authoritative artifact manifest for first-pass diagnosis. Keeping
+ * that manifest intact prevents the CLI from becoming less authoritative than
+ * the API. Raw regions and scoring details stay behind an explicit include
+ * because they can dominate an otherwise bounded handoff.
  *
  * @param {Object} comparison - Comparison record from the API.
  * @param {boolean} includeDiffs - Whether to include raw Honeydiff diagnostics.
@@ -158,6 +160,7 @@ function getComparisonDiff(comparison = {}, includeDiffs = false) {
   let analysis = comparison.analysis || {};
   let regions = diff.regions || diff.diff_regions || analysis.diff_regions || comparison.diff_regions;
   let projection = diff.projection || diff.analysis_projection || analysis.projection || analysis.analysis_projection || comparison.analysis_projection || comparison.projection || null;
+  let artifacts = diff.artifacts ?? analysis.artifacts ?? comparison.artifacts ?? null;
   let compact = {
     percentage: diff.percentage ?? analysis.percentage ?? analysis.diff_percentage ?? comparison.diff_percentage ?? null,
     changed_pixels: diff.changed_pixels ?? analysis.changed_pixels ?? comparison.changed_pixels ?? null,
@@ -168,6 +171,12 @@ function getComparisonDiff(comparison = {}, includeDiffs = false) {
     projection,
     image_url: diff.image_url || diff.url || analysis.diff_image_url || comparison.diff_url || comparison.diff_image_url || null
   };
+
+  // Preserve server-owned evidence exactly so agents can verify and download
+  // artifacts without the CLI recreating identities, digests, or availability.
+  if (artifacts != null) {
+    compact.artifacts = artifacts;
+  }
   if (includeDiffs) {
     compact.regions = regions || [];
     compact.cluster_metadata = diff.cluster_metadata || analysis.cluster_metadata || comparison.cluster_metadata || null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.35.3-beta.0",
+  "version": "0.35.3-beta.1",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",
@@ -60,7 +60,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "cli": "source .envrc && node bin/vizzly.js",
+    "cli": "node scripts/run-development-cli.js production",
+    "cli:local": "node scripts/run-development-cli.js local",
     "start": "node src/index.js",
     "build": "pnpm run clean && pnpm run compile && pnpm run build:reporter && pnpm run build:reporter-ssr && pnpm run copy-types",
     "clean": "rimraf dist",
@@ -93,7 +94,7 @@
   },
   "dependencies": {
     "@vizzly-testing/bear-den": "0.1.4",
-    "@vizzly-testing/honeydiff": "^0.11.1",
+    "@vizzly-testing/honeydiff": "^0.15.0",
     "ansis": "^4.2.0",
     "commander": "^15.0.0",
     "cosmiconfig": "^9.0.0",
@@ -115,18 +116,18 @@
     }
   },
   "devDependencies": {
-    "@babel/cli": "^7.28.0",
-    "@babel/core": "^7.23.6",
-    "@babel/preset-env": "^7.23.6",
-    "@babel/preset-react": "^7.27.1",
-    "@babel/preset-typescript": "^7.23.6",
+    "@babel/cli": "^8.0.1",
+    "@babel/core": "^8.0.1",
+    "@babel/preset-env": "^8.0.2",
+    "@babel/preset-react": "^8.0.1",
+    "@babel/preset-typescript": "^8.0.1",
     "@biomejs/biome": "^2.3.8",
     "@heroicons/react": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.0.4",
     "@playwright/test": "^1.55.1",
     "@tailwindcss/postcss": "^4.1.13",
     "@tanstack/react-query": "^5.90.11",
-    "@types/node": "^25.0.2",
+    "@types/node": "^26.0.0",
     "@vitejs/plugin-react": "^6.0.1",
     "autoprefixer": "^10.4.21",
     "babel-plugin-react-compiler": "^1.0.0",
@@ -136,7 +137,7 @@
     "tailwindcss": "^4.1.13",
     "tsd": "^0.33.0",
     "tui-driver": "github:vizzly-testing/tui-driver",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vite": "^8.0.0",
     "wouter": "^3.7.1"
   }

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

@@ -84,7 +84,7 @@ For each evidence record:
 Useful manual drill-downs are:
 
 ```bash
-vizzly context comparison <comparison-id> --source <local-or-cloud> --json
+vizzly context comparison <comparison-id> --source <local-or-cloud> --agent --json
 vizzly context screenshot "<screenshot-name>" --source <local-or-cloud> --json
 vizzly context similar <fingerprint-hash> --source cloud --json
 vizzly context review-queue --source <local-or-cloud> --json
@@ -94,3 +94,7 @@ Use the source from the evidence you are inspecting in place of
 `<local-or-cloud>`. `context similar` is cloud-only. Keep missing values
 unknown, and do not turn metadata into a visual conclusion when the underlying
 images are unavailable.
+
+When a build has more than 10 actionable records, run its returned next-page
+command. The command uses `--offset` to preserve API order without pulling the
+full build context into the agent handoff.

package/dist/config/index.js

@@ -1,13 +0,0 @@
-/**
- * Config Module - Public exports
- *
- * Provides functional configuration primitives:
- * - core.js: Pure functions for merging, serialization, validation results
- * - operations.js: Config operations with dependency injection
- */
-
-// Core pure functions
-export { buildGlobalConfigResult, buildMergedConfig, buildMergedConfigResult, buildProjectConfigResult, buildValidationFailure, buildValidationSuccess, CONFIG_DEFAULTS, deepMerge, extractCosmiconfigResult, extractEnvOverrides, getConfigFormat, READ_SCOPES, serializeConfig, serializeToJavaScript, serializeToJson, stringifyWithIndent, validateReadScope, validateWriteScope, WRITE_SCOPES } from './core.js';
-
-// Config operations (take dependencies as parameters)
-export { getConfig, getConfigSource, getGlobalConfig, getMergedConfig, getProjectConfig, updateConfig, updateGlobalConfig, updateProjectConfig, validateConfig, writeProjectConfigFile } from './operations.js';

package/dist/project/index.js

@@ -1,13 +0,0 @@
-/**
- * Project Module - Public exports
- *
- * Provides functional project management primitives:
- * - core.js: Pure functions for validation, URL building, response extraction
- * - operations.js: Project operations with dependency injection
- */
-
-// Core pure functions
-export { buildBuildsQueryParams, buildBuildsUrl, buildMappingResult, buildNoApiServiceError, buildNoAuthError, buildOrgHeader, buildProjectFetchError, buildProjectUrl, buildTokenCreateError, buildTokenRevokeError, buildTokensFetchError, buildTokensUrl, enrichProjectsWithOrg, extractBuilds, extractOrganizations, extractProject, extractProjects, extractToken, extractTokens, mappingsToArray, validateDirectory, validateProjectData } from './core.js';
-
-// Project operations (take dependencies as parameters)
-export { createMapping, createProjectToken, getMapping, getProject, getProjectWithApiToken, getProjectWithOAuth, getRecentBuilds, getRecentBuildsWithApiToken, getRecentBuildsWithOAuth, listMappings, listProjects, listProjectsWithApiToken, listProjectsWithOAuth, listProjectTokens, removeMapping, revokeProjectToken, switchProject } from './operations.js';

package/dist/tdd/index.js

@@ -1,19 +0,0 @@
-/**
- * TDD Module Exports
- *
- * Re-exports all TDD functionality for clean imports.
- */
-
-export { calculateHotspotCoverage, shouldFilterAsHotspot } from './core/hotspot-coverage.js';
-// Core pure functions
-export { generateBaselineFilename, generateComparisonId, generateScreenshotSignature } from './core/signature.js';
-
-// Metadata I/O
-export { createEmptyBaselineMetadata, findScreenshotBySignature, loadBaselineMetadata, saveBaselineMetadata, upsertScreenshotInMetadata } from './metadata/baseline-metadata.js';
-export { createHotspotCache, getHotspotForScreenshot, loadHotspotMetadata, saveHotspotMetadata } from './metadata/hotspot-metadata.js';
-export { baselineMatchesSha, buildBaselineMetadataEntry, downloadBaselineImage, downloadBaselinesInBatches } from './services/baseline-downloader.js';
-// Services
-export { baselineExists, clearBaselineData, getBaselinePath, getCurrentPath, getDiffPath, initializeDirectories, promoteCurrentToBaseline, readBaseline, readCurrent, saveBaseline, saveCurrent } from './services/baseline-manager.js';
-export { buildErrorComparison, buildFailedComparison, buildNewComparison, buildPassedComparison, compareImages, isDimensionMismatchError } from './services/comparison-service.js';
-export { downloadHotspots } from './services/hotspot-service.js';
-export { buildResults, calculateSummary, findComparison, findComparisonById, getErrorComparisons, getFailedComparisons, getNewComparisons, isSuccessful } from './services/result-service.js';

package/dist/tdd/services/baseline-downloader.js

@@ -1,151 +0,0 @@
-/**
- * Baseline Downloader
- *
- * Functions for downloading baseline images from the cloud API.
- * These are lower-level utilities - orchestration happens in TddService.
- */
-
-import { existsSync, writeFileSync } from 'node:fs';
-import { fetchWithTimeout } from '../../utils/fetch-utils.js';
-
-/**
- * Download a single baseline image
- *
- * @param {string} url - URL to download from
- * @param {string} destPath - Destination file path
- * @param {Object} options - Options
- * @param {number} options.timeout - Request timeout in ms (default: 30000)
- * @returns {Promise<{ success: boolean, error?: string }>}
- */
-export async function downloadBaselineImage(url, destPath, options = {}) {
-  let {
-    timeout = 30000
-  } = options;
-  try {
-    let response = await fetchWithTimeout(url, {
-      timeout
-    });
-    if (!response.ok) {
-      return {
-        success: false,
-        error: `HTTP ${response.status}: ${response.statusText}`
-      };
-    }
-    let buffer = Buffer.from(await response.arrayBuffer());
-    writeFileSync(destPath, buffer);
-    return {
-      success: true
-    };
-  } catch (error) {
-    return {
-      success: false,
-      error: error.message
-    };
-  }
-}
-
-/**
- * Check if a baseline already exists with matching SHA
- *
- * @param {string} filePath - Path to the baseline file
- * @param {string} expectedSha - Expected SHA256 hash
- * @param {Map<string, string>} shaMap - Map of filename -> sha256
- * @returns {boolean}
- */
-export function baselineMatchesSha(filePath, expectedSha, shaMap) {
-  if (!existsSync(filePath) || !expectedSha) {
-    return false;
-  }
-  let filename = filePath.split('/').pop();
-  let storedSha = shaMap.get(filename);
-  return storedSha === expectedSha;
-}
-
-/**
- * Download multiple baselines in batches
- *
- * @param {Array} screenshots - Screenshots to download
- * @param {Object} options - Options
- * @param {string} options.baselinePath - Path to baselines directory
- * @param {Map<string, string>} options.existingShaMap - Existing SHA map for skip logic
- * @param {number} options.batchSize - Concurrent downloads (default: 5)
- * @param {Function} options.onProgress - Progress callback (downloaded, skipped, errors, total)
- * @param {Function} options.getFilePath - Function to get file path for a screenshot
- * @returns {Promise<{ downloaded: number, skipped: number, errors: number }>}
- */
-export async function downloadBaselinesInBatches(screenshots, options = {}) {
-  let {
-    existingShaMap = new Map(),
-    batchSize = 5,
-    onProgress,
-    getFilePath
-  } = options;
-  let downloaded = 0;
-  let skipped = 0;
-  let errors = 0;
-  let total = screenshots.length;
-
-  // Process in batches
-  for (let i = 0; i < screenshots.length; i += batchSize) {
-    let batch = screenshots.slice(i, i + batchSize);
-    let batchPromises = batch.map(async screenshot => {
-      let filePath = getFilePath(screenshot);
-      let url = screenshot.original_url;
-      if (!url) {
-        errors++;
-        return;
-      }
-
-      // Skip if SHA matches
-      if (baselineMatchesSha(filePath, screenshot.sha256, existingShaMap)) {
-        skipped++;
-        downloaded++;
-        return;
-      }
-      let result = await downloadBaselineImage(url, filePath);
-      if (result.success) {
-        downloaded++;
-      } else {
-        errors++;
-      }
-    });
-    await Promise.all(batchPromises);
-    if (onProgress) {
-      onProgress(downloaded, skipped, errors, total);
-    }
-  }
-  return {
-    downloaded,
-    skipped,
-    errors
-  };
-}
-
-/**
- * Build baseline metadata entry for a downloaded screenshot
- *
- * @param {Object} screenshot - Screenshot data from API
- * @param {string} filename - Local filename
- * @param {string} filePath - Full file path
- * @param {Object} buildInfo - Build information
- * @returns {Object} Metadata entry
- */
-export function buildBaselineMetadataEntry(screenshot, filename, filePath, buildInfo = {}) {
-  return {
-    name: screenshot.name,
-    originalName: screenshot.name,
-    sha256: screenshot.sha256,
-    id: screenshot.id,
-    filename,
-    path: filePath,
-    browser: screenshot.browser || screenshot.metadata?.browser,
-    viewport_width: screenshot.viewport_width || screenshot.metadata?.viewport?.width || screenshot.properties?.viewport?.width,
-    originalUrl: screenshot.original_url,
-    fileSize: screenshot.file_size,
-    dimensions: screenshot.dimensions,
-    // Build info for tracking
-    buildId: buildInfo.buildId,
-    commitSha: buildInfo.commitSha,
-    approvalStatus: screenshot.approval_status
-  };
-}

package/dist/tdd/services/hotspot-service.js

@@ -1,58 +0,0 @@
-/**
- * Hotspot Service
- *
- * Functions for downloading and managing hotspot data from the cloud.
- * Hotspots identify regions that frequently change due to dynamic content.
- */
-
-import { saveHotspotMetadata } from '../metadata/hotspot-metadata.js';
-
-/**
- * Download hotspots for screenshots from cloud API
- *
- * @param {Object} options
- * @param {Object} options.api - ApiService instance
- * @param {string} options.workingDir - Working directory
- * @param {string[]} options.screenshotNames - Names of screenshots to get hotspots for
- * @returns {Promise<{ success: boolean, count: number, regionCount: number, error?: string }>}
- */
-export async function downloadHotspots(options) {
-  let {
-    api,
-    workingDir,
-    screenshotNames
-  } = options;
-  if (!screenshotNames || screenshotNames.length === 0) {
-    return {
-      success: true,
-      count: 0,
-      regionCount: 0
-    };
-  }
-  try {
-    let response = await api.getHotspots(screenshotNames);
-    if (!response?.hotspots) {
-      return {
-        success: false,
-        error: 'API returned no hotspot data'
-      };
-    }
-
-    // Save hotspots to disk
-    saveHotspotMetadata(workingDir, response.hotspots, response.summary);
-
-    // Calculate stats
-    let count = Object.keys(response.hotspots).length;
-    let regionCount = Object.values(response.hotspots).reduce((sum, h) => sum + (h.regions?.length || 0), 0);
-    return {
-      success: true,
-      count,
-      regionCount
-    };
-  } catch (error) {
-    return {
-      success: false,
-      error: error.message
-    };
-  }
-}

package/dist/utils/environment.js

@@ -1,109 +0,0 @@
-/**
- * Environment detection utilities for handling CI/interactive environments
- */
-
-/**
- * Check if running in a CI environment
- * Based on common CI environment variables
- * @returns {boolean} True if running in CI
- */
-export function isCI() {
-  return Boolean(process.env.CI ||
-  // Generic CI flag
-  process.env.CONTINUOUS_INTEGRATION ||
-  // TravisCI, CircleCI
-  process.env.BUILD_NUMBER ||
-  // Jenkins
-  process.env.GITHUB_ACTIONS ||
-  // GitHub Actions
-  process.env.GITLAB_CI ||
-  // GitLab CI
-  process.env.CIRCLECI ||
-  // CircleCI
-  process.env.TRAVIS ||
-  // TravisCI
-  process.env.APPVEYOR ||
-  // AppVeyor
-  process.env.CODEBUILD_BUILD_ID ||
-  // AWS CodeBuild
-  process.env.TEAMCITY_VERSION ||
-  // TeamCity
-  process.env.TF_BUILD ||
-  // Azure DevOps
-  process.env.DRONE ||
-  // Drone CI
-  process.env.BITBUCKET_BUILD_NUMBER // Bitbucket Pipelines
-  );
-}
-
-/**
- * Check if stdout supports interactive features
- * @returns {boolean} True if interactive features are supported
- */
-export function isInteractiveTerminal() {
-  return Boolean(process.stdout.isTTY && process.stdin.isTTY && (!process.env.TERM || process.env.TERM !== 'dumb'));
-}
-
-/**
- * Determine if interactive mode should be enabled
- * Takes into account CI detection, TTY support, and explicit flags
- * @param {Object} options
- * @param {boolean} [options.noInteractive] - Explicit flag to disable interactive mode
- * @param {boolean} [options.interactive] - Explicit flag to force interactive mode
- * @returns {boolean} True if interactive mode should be enabled
- */
-export function shouldUseInteractiveMode(options = {}) {
-  // Explicit flags take priority
-  // Commander.js sets interactive=false when --no-interactive is used
-  if (options.interactive === false) {
-    return false;
-  }
-  if (options.interactive === true) {
-    return true;
-  }
-
-  // Legacy support for explicit noInteractive flag
-  if (options.noInteractive === true) {
-    return false;
-  }
-
-  // Auto-detect based on environment
-  return !isCI() && isInteractiveTerminal();
-}
-
-/**
- * Get environment type for logging/debugging
- * @returns {string} Environment type description
- */
-export function getEnvironmentType() {
-  if (isCI()) {
-    return 'CI';
-  }
-  if (!isInteractiveTerminal()) {
-    return 'non-interactive';
-  }
-  return 'interactive';
-}
-
-/**
- * Get detailed environment info for debugging
- * @returns {Object} Environment details
- */
-export function getEnvironmentDetails() {
-  return {
-    isCI: isCI(),
-    isInteractiveTerminal: isInteractiveTerminal(),
-    environmentType: getEnvironmentType(),
-    stdoutIsTTY: Boolean(process.stdout.isTTY),
-    stdinIsTTY: Boolean(process.stdin.isTTY),
-    ciVars: {
-      CI: process.env.CI,
-      CONTINUOUS_INTEGRATION: process.env.CONTINUOUS_INTEGRATION,
-      GITHUB_ACTIONS: process.env.GITHUB_ACTIONS,
-      GITLAB_CI: process.env.GITLAB_CI,
-      CIRCLECI: process.env.CIRCLECI,
-      TRAVIS: process.env.TRAVIS
-    },
-    termType: process.env.TERM
-  };
-}