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

package/skills/vizzly/references/setup-ci.md

@@ -1,10 +1,10 @@
 # Setup And CI
 
-Use this reference only when the user asks to initialize Vizzly, change CI, or
-troubleshoot configuration. These workflows mutate project files or external
-build state.
+Use this reference only when the task includes initialization, CI changes, or
+configuration troubleshooting. These workflows mutate files or external build
+state.
 
-## Local Setup
+## Initialize
 
 Initialize only with authorization:
 
@@ -12,57 +12,33 @@ Initialize only with authorization:
 vizzly init
 ```
 
-After setup, choose one local execution mode:
-
-```bash
-vizzly tdd run "<existing visual test command>" --no-open
-```
-
-or:
-
-```bash
-vizzly tdd start --json
-<existing visual test command>
-vizzly tdd stop --json
-```
-
-Do not run `tdd start` before `tdd run`; both own a local TDD server lifecycle.
+Use [CLI context](cli-context.md) for local evidence and TDD lifecycle commands.
 
 ## Cloud CI
 
-Use a project-scoped token supplied by the user's existing secret-management
-system. Never print it, write it into the repository, or replace working
-credentials while debugging.
-
-Wrap the CI job's existing visual test command:
+Use a project-scoped token from the repository's existing secret system. Never
+print it or write it into the repository.
 
 ```bash
 vizzly run "<existing visual test command>" --wait --json
 ```
 
-## Parallel CI
-
-Give every shard in one build the same parallel ID, unique to that workflow
-attempt. Run all shards without `--wait`, then finalize that shared ID once
-after every shard finishes:
+For parallel CI, give every shard the same workflow-specific parallel ID. Run
+shards without `--wait`, then finalize once after all shards finish:
 
 ```bash
 vizzly run "<shard test command>" --parallel-id "<shared-ci-run-id>" --json
 vizzly finalize "<shared-ci-run-id>" --json
 ```
 
-Do not create a different parallel ID per shard, and do not wait for a parallel
-build to complete before it has been finalized. Use one finalizer rather than
-having every shard race to finalize the build.
-
 ## Troubleshoot
 
-- Run `vizzly doctor` for local configuration checks.
-- Run `vizzly tdd status --json` for a local daemon started by the task.
-- Run `vizzly status <build-id> --json` for cloud lifecycle facts.
-- Run `vizzly context build <build-id> --source cloud --agent --json` for visual
-  evidence.
-- If screenshots are absent, verify the existing SDK or integration, the test
-  path that should capture them, and the active local or cloud session.
-- If authentication is absent, report it rather than initiating login unless
-  setup is explicitly in scope.
+- `vizzly doctor`: local configuration
+- `vizzly tdd status --json`: a local daemon started by the task
+- `vizzly status <build-id> --json`: cloud lifecycle
+- `vizzly context build <build-id> --source cloud --agent --json`: visual
+  evidence
+
+If screenshots are absent, verify the existing integration, the test path that
+should capture them, and the active session. If authentication is absent,
+report it rather than logging in unless setup is in scope.

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
-  };
-}

package/skills/vizzly/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Vizzly"
-  short_description: "Inspect and debug visual changes with Vizzly"
-  default_prompt: "Use $vizzly to inspect the visual evidence for this UI change and explain what changed."