@vizzly-testing/cli 0.39.1 → 0.39.2

package/dist/domains/screenshots/cloud-screenshots.js

@@ -0,0 +1,109 @@
+import * as output from '../../shared/output.js';
+import { buildScreenshotPayload, buildScreenshotResolvePayload, buildShaCheckPayload } from './screenshot.serializers.js';
+import { computeSha256 } from './screenshot-hash.js';
+
+/**
+ * Check if SHAs already exist on the server
+ * @param {Object} client - API client
+ * @param {Array} screenshots - Screenshots to check (objects with sha256, or string SHAs)
+ * @param {string} buildId - Build ID for screenshot record creation
+ * @returns {Promise<Object>} { existing, missing, screenshots }
+ */
+export async function checkShas(client, screenshots, buildId) {
+  try {
+    let payload = buildShaCheckPayload(screenshots, buildId);
+    return await client.request('/api/sdk/check-shas', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(payload)
+    });
+  } catch (error) {
+    // Continue without deduplication on error
+    output.debug('sha-check', 'failed, continuing without deduplication', {
+      error: error.message
+    });
+
+    // Extract SHAs for fallback response
+    let shaList = Array.isArray(screenshots) && screenshots.length > 0 && typeof screenshots[0] === 'object' ? screenshots.map(s => s.sha256) : screenshots;
+    return {
+      existing: [],
+      missing: shaList,
+      screenshots: []
+    };
+  }
+}
+function canUploadBytesAfterShaResolveError(error) {
+  let status = error?.context?.status;
+
+  // Network failures, older servers, and server errors should degrade to the
+  // slower byte upload path. Auth and ownership errors must still surface.
+  if (!status) return true;
+  if (status >= 500) return true;
+  if (status === 400 && error.message?.includes('image_data')) return true;
+  return false;
+}
+
+/**
+ * Upload a screenshot with SHA deduplication
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @param {string} name - Screenshot name
+ * @param {Buffer} buffer - Screenshot data
+ * @param {Object} metadata - Additional metadata
+ * @param {boolean} skipDedup - Skip SHA deduplication (uploadAll mode)
+ * @returns {Promise<Object>} Upload result
+ */
+export async function uploadScreenshot(client, buildId, name, buffer, metadata = {}, skipDedup = false, screenshotOptions = {}) {
+  // Skip SHA deduplication if requested
+  if (skipDedup) {
+    let payload = buildScreenshotPayload(name, buffer, metadata, null, screenshotOptions);
+    return client.request(`/api/sdk/builds/${buildId}/screenshots`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(payload)
+    });
+  }
+
+  // Normal flow with server-side SHA resolution.
+  let sha256 = computeSha256(buffer);
+  let resolvePayload = buildScreenshotResolvePayload(name, metadata, sha256, screenshotOptions);
+  try {
+    let resolveResult = await client.request(`/api/sdk/builds/${buildId}/screenshots`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(resolvePayload)
+    });
+    if (resolveResult?.upload_required === false) {
+      return {
+        message: 'Screenshot already exists, skipped upload',
+        sha256,
+        skipped: true,
+        screenshot: resolveResult,
+        fromExisting: true
+      };
+    }
+  } catch (error) {
+    if (!canUploadBytesAfterShaResolveError(error)) {
+      throw error;
+    }
+    output.debug('sha-resolve', 'failed, uploading screenshot bytes', {
+      error: error.message
+    });
+  }
+
+  // File doesn't exist, or resolve failed; proceed with upload.
+  let payload = buildScreenshotPayload(name, buffer, metadata, sha256, screenshotOptions);
+  return client.request(`/api/sdk/builds/${buildId}/screenshots`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(payload)
+  });
+}

package/dist/{utils/file-helpers.js → domains/screenshots/image-files.js}

@@ -5,7 +5,7 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { VizzlyError } from '../errors/vizzly-error.js';
+import { VizzlyError } from '../../shared/vizzly-error.js';
 
 /**
  * Resolve image buffer from file path or return buffer as-is

package/dist/domains/screenshots/screenshot-hash.js

@@ -0,0 +1,53 @@
+import crypto from 'node:crypto';
+
+/**
+ * Compute SHA256 hash of buffer
+ * @param {Buffer} buffer - Data to hash
+ * @returns {string} Hex-encoded SHA256 hash
+ */
+export function computeSha256(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+/**
+ * Partition screenshots by SHA existence
+ * @param {Array<Object>} screenshots - Screenshots with sha256 property
+ * @param {Set<string>|Array<string>} existingShas - SHAs that already exist
+ * @returns {Object} { toUpload, existing } partitioned arrays
+ */
+export function partitionByShaExistence(screenshots, existingShas) {
+  let existingSet = existingShas instanceof Set ? existingShas : new Set(existingShas);
+  let toUpload = [];
+  let existing = [];
+  for (let screenshot of screenshots) {
+    if (existingSet.has(screenshot.sha256)) {
+      existing.push(screenshot);
+    } else {
+      toUpload.push(screenshot);
+    }
+  }
+  return {
+    toUpload,
+    existing
+  };
+}
+
+/**
+ * Check if SHA check result indicates file exists
+ * @param {Object} checkResult - Result from checkShas endpoint
+ * @param {string} sha256 - SHA to check
+ * @returns {boolean} True if file exists
+ */
+export function shaExists(checkResult, sha256) {
+  return checkResult?.existing?.includes(sha256) ?? false;
+}
+
+/**
+ * Find screenshot record from SHA check result
+ * @param {Object} checkResult - Result from checkShas endpoint
+ * @param {string} sha256 - SHA to find
+ * @returns {Object|null} Screenshot record or null
+ */
+export function findScreenshotBySha(checkResult, sha256) {
+  return checkResult?.screenshots?.find(s => s.sha256 === sha256) ?? null;
+}

package/dist/domains/screenshots/screenshot-server-options.js

@@ -0,0 +1,28 @@
+/**
+ * Build server listen options
+ * @param {Object} config - Server configuration
+ * @returns {{ port: number, host: string }}
+ */
+export function buildServerListenOptions(config) {
+  return {
+    port: config?.server?.port || 3000,
+    host: '127.0.0.1'
+  };
+}
+
+/**
+ * Build server started message
+ * @param {number} port - Server port
+ * @returns {string}
+ */
+export function buildServerStartedMessage(port) {
+  return `Screenshot server listening on http://127.0.0.1:${port}`;
+}
+
+/**
+ * Build server stopped message
+ * @returns {string}
+ */
+export function buildServerStoppedMessage() {
+  return 'Screenshot server stopped';
+}

package/dist/{screenshot-server/operations.js → domains/screenshots/screenshot-server.js}

@@ -4,7 +4,10 @@
  * Each operation takes its dependencies as parameters for testability.
  */
 
-import { buildBadRequestResponse, buildInternalErrorResponse, buildNotFoundResponse, buildServerListenOptions, buildServerStartedMessage, buildServerStoppedMessage, buildSuccessResponse, extractScreenshotData, getEffectiveBuildId, isScreenshotEndpoint, validateScreenshotRequest } from './core.js';
+import { extractScreenshotData, getEffectiveBuildId } from './screenshot.normalizers.js';
+import { buildBadRequestResponse, buildInternalErrorResponse, buildNotFoundResponse, buildSuccessResponse } from './screenshot.serializers.js';
+import { validateScreenshotRequest } from './screenshot.validations.js';
+import { buildServerListenOptions, buildServerStartedMessage, buildServerStoppedMessage } from './screenshot-server-options.js';
 
 // ============================================================================
 // Request Body Parsing
@@ -180,4 +183,14 @@ export function stopServer({
       resolve();
     });
   });
+}
+
+/**
+ * Check if request is for the screenshot endpoint
+ * @param {string} method - HTTP method
+ * @param {string} url - Request URL
+ * @returns {boolean}
+ */
+export function isScreenshotEndpoint(method, url) {
+  return method === 'POST' && url === '/screenshot';
 }

package/dist/domains/screenshots/screenshot.normalizers.js

@@ -0,0 +1,40 @@
+import { getScreenshotOptionsPayload } from './screenshot-options.js';
+
+/**
+ * Get effective build ID (falls back to 'default')
+ * @param {string|null|undefined} buildId - Build ID from request
+ * @returns {string}
+ */
+export function getEffectiveBuildId(buildId) {
+  return buildId || 'default';
+}
+
+/**
+ * Extract screenshot data from request body
+ * @param {Object} body - Request body
+ * @returns {{ name: string, image: string, properties?: Object }}
+ */
+export function extractScreenshotData(body) {
+  let screenshotData = {
+    name: body.name,
+    image: body.image,
+    properties: body.properties
+  };
+  Object.assign(screenshotData, getScreenshotOptionsPayload(body));
+  return screenshotData;
+}
+
+/**
+ * Build the flat internal comparison shape. Width and height always come from
+ * the captured image. The untouched user bag remains available in metadata.
+ */
+export let extractProperties = (validatedProperties, imageDimensions = {}) => {
+  if (!validatedProperties) return {};
+  return {
+    ...validatedProperties,
+    viewport_width: imageDimensions.width ?? null,
+    viewport_height: imageDimensions.height ?? null,
+    browser: validatedProperties.browser ?? null,
+    metadata: validatedProperties
+  };
+};

package/dist/{server/routers/screenshot.js → domains/screenshots/screenshot.routes.js}

@@ -3,10 +3,10 @@
  * Handles screenshot uploads and flush requests.
  */
 
-import * as output from '../../utils/output.js';
-import { normalizeScreenshotOptions } from '../../utils/screenshot-options.js';
-import { parseJsonBody } from '../middleware/json-parser.js';
-import { sendError, sendJson } from '../middleware/response.js';
+import { parseJsonBody } from '../../adapters/http/middleware/json-parser.js';
+import { sendError, sendJson } from '../../adapters/http/middleware/response.js';
+import * as output from '../../shared/output.js';
+import { normalizeScreenshotOptions } from './screenshot-options.js';
 
 /**
  * Route local capture and flush requests to the active cloud or TDD handler.

package/dist/domains/screenshots/screenshot.serializers.js

@@ -0,0 +1,146 @@
+import { createScreenshotProperties, getScreenshotOptionsPayload } from './screenshot-options.js';
+
+/**
+ * Build payload for screenshot upload or SHA resolution
+ * @param {string} name - Screenshot name
+ * @param {Buffer|null} buffer - Image data, or null when resolving by SHA
+ * @param {Object} metadata - User screenshot properties
+ * @param {string|null} sha256 - Pre-computed SHA256 hash (optional)
+ * @returns {Object} Screenshot upload payload
+ */
+export function buildScreenshotPayload(name, buffer, metadata = {}, sha256 = null, screenshotOptions = {}) {
+  let payload = {
+    name,
+    properties: createScreenshotProperties({
+      properties: metadata
+    })
+  };
+  Object.assign(payload, getScreenshotOptionsPayload(screenshotOptions));
+  if (buffer) {
+    payload.image_data = buffer.toString('base64');
+  }
+  if (sha256) {
+    payload.sha256 = sha256;
+  }
+  return payload;
+}
+
+/**
+ * Build payload for server-side screenshot resolution without sending image bytes
+ * @param {string} name - Screenshot name
+ * @param {Object} metadata - User screenshot properties
+ * @param {string} sha256 - Pre-computed SHA256 hash
+ * @returns {Object} Screenshot resolution payload
+ */
+export function buildScreenshotResolvePayload(name, metadata = {}, sha256, screenshotOptions = {}) {
+  return buildScreenshotPayload(name, null, metadata, sha256, screenshotOptions);
+}
+
+/**
+ * Build payload for SHA existence check (signature-based format)
+ * @param {Array<Object>} screenshots - Screenshots with sha256 and metadata
+ * @param {string} buildId - Build ID for screenshot record creation
+ * @returns {Object} SHA check request payload
+ */
+export function buildShaCheckPayload(screenshots, buildId) {
+  // Check if using new signature-based format or legacy SHA-only format
+  if (screenshots.length > 0 && typeof screenshots[0] === 'object' && screenshots[0].sha256) {
+    return {
+      buildId,
+      screenshots
+    };
+  }
+
+  // Legacy format: array of SHA strings
+  return {
+    shas: screenshots,
+    buildId
+  };
+}
+
+/**
+ * Build screenshot object for SHA checking
+ * @param {string} sha256 - SHA256 hash of image
+ * @param {string} name - Screenshot name
+ * @param {Object} metadata - Screenshot metadata
+ * @returns {Object} Screenshot check object
+ */
+export function buildScreenshotCheckObject(sha256, name, metadata = {}) {
+  let meta = metadata || {};
+  let properties = createScreenshotProperties({
+    properties: meta
+  });
+  return {
+    sha256,
+    name,
+    properties
+  };
+}
+
+/**
+ * Build success response object
+ * @returns {{ status: number, body: Object }}
+ */
+export function buildSuccessResponse() {
+  return {
+    status: 200,
+    body: {
+      success: true
+    }
+  };
+}
+
+/**
+ * Build error response object
+ * @param {number} status - HTTP status code
+ * @param {string} message - Error message
+ * @returns {{ status: number, body: Object }}
+ */
+export function buildErrorResponse(status, message) {
+  return {
+    status,
+    body: {
+      error: message
+    }
+  };
+}
+
+/**
+ * Build not found response
+ * @returns {{ status: number, body: Object }}
+ */
+export function buildNotFoundResponse() {
+  return buildErrorResponse(404, 'Not found');
+}
+
+/**
+ * Build bad request response
+ * @param {string} message - Error message
+ * @returns {{ status: number, body: Object }}
+ */
+export function buildBadRequestResponse(message) {
+  return buildErrorResponse(400, message);
+}
+
+/**
+ * Build internal error response
+ * @returns {{ status: number, body: Object }}
+ */
+export function buildInternalErrorResponse() {
+  return buildErrorResponse(500, 'Internal server error');
+}
+export function serializeScreenshotRequest({
+  buildId,
+  name,
+  image,
+  type
+}, options) {
+  return {
+    buildId,
+    name,
+    image,
+    type,
+    properties: options.properties,
+    ...getScreenshotOptionsPayload(options)
+  };
+}

package/dist/{utils/security.js → domains/screenshots/screenshot.validations.js}

@@ -1,18 +1,5 @@
-/**
- * Security utilities for path sanitization and validation
- * Protects against path traversal attacks and ensures safe file operations
- */
+import { isAbsolute } from 'node:path';
 
-import { isAbsolute, join, normalize, resolve } from 'node:path';
-import * as output from './output.js';
-
-/**
- * Sanitizes a screenshot name to prevent path traversal and ensure safe file naming
- * @param {string} name - Original screenshot name
- * @param {number} maxLength - Maximum allowed length (default: 255)
- * @param {boolean} allowSlashes - Whether to allow forward slashes (for browser version strings)
- * @returns {string} Sanitized screenshot name
- */
 /**
  * Validate screenshot name for security (no transformations, just validation)
  * Throws if name contains path traversal or other dangerous patterns
@@ -95,7 +82,7 @@ export function sanitizeScreenshotName(name, maxLength = 255, allowSlashes = fal
   // Allow only safe characters: alphanumeric, hyphens, underscores, dots, spaces, and optionally slashes
   // Spaces are allowed here and will be converted to hyphens in generateBaselineFilename() to match cloud behavior
   // Replace other characters with underscores
-  const allowedChars = allowSlashes ? /[^a-zA-Z0-9._ /-]/g : /[^a-zA-Z0-9._ -]/g;
+  let allowedChars = allowSlashes ? /[^a-zA-Z0-9._ /-]/g : /[^a-zA-Z0-9._ -]/g;
   let sanitized = name.replace(allowedChars, '_');
 
   // Prevent names that start with dots (hidden files)
@@ -110,61 +97,6 @@ export function sanitizeScreenshotName(name, maxLength = 255, allowSlashes = fal
   return sanitized;
 }
 
-/**
- * Validates that a path stays within the allowed working directory bounds
- * @param {string} targetPath - Path to validate
- * @param {string} workingDir - Working directory that serves as the security boundary
- * @returns {string} Resolved and normalized path if valid
- * @throws {Error} If path is invalid or outside bounds
- */
-export function validatePathSecurity(targetPath, workingDir) {
-  if (typeof targetPath !== 'string' || targetPath.length === 0) {
-    throw new Error('Path must be a non-empty string');
-  }
-  if (typeof workingDir !== 'string' || workingDir.length === 0) {
-    throw new Error('Working directory must be a non-empty string');
-  }
-
-  // Normalize and resolve both paths
-  const resolvedWorkingDir = resolve(normalize(workingDir));
-  const resolvedTargetPath = resolve(normalize(targetPath));
-
-  // Ensure the target path starts with the working directory
-  if (!resolvedTargetPath.startsWith(resolvedWorkingDir)) {
-    output.warn(`Path traversal attempt blocked: ${targetPath} (resolved: ${resolvedTargetPath}) is outside working directory: ${resolvedWorkingDir}`);
-    throw new Error('Path is outside the allowed working directory');
-  }
-  return resolvedTargetPath;
-}
-
-/**
- * Safely constructs a path within the working directory
- * @param {string} workingDir - Base working directory
- * @param {...string} pathSegments - Path segments to join
- * @returns {string} Safely constructed path
- * @throws {Error} If resulting path would be outside working directory
- */
-export function safePath(workingDir, ...pathSegments) {
-  if (pathSegments.length === 0) {
-    return validatePathSecurity(workingDir, workingDir);
-  }
-
-  // Sanitize each path segment
-  const sanitizedSegments = pathSegments.map(segment => {
-    if (typeof segment !== 'string') {
-      throw new Error('Path segment must be a string');
-    }
-
-    // Block directory traversal in segments
-    if (segment.includes('..')) {
-      throw new Error('Path segment contains directory traversal sequence');
-    }
-    return segment;
-  });
-  const targetPath = join(workingDir, ...sanitizedSegments);
-  return validatePathSecurity(targetPath, workingDir);
-}
-
 /**
  * Validate user metadata without interpreting names as Vizzly options or
  * rewriting values. Rendering code must escape strings for its output context.
@@ -202,4 +134,22 @@ export function validateScreenshotProperties(properties = {}) {
     return result;
   }
   return copy(properties);
+}
+
+/**
+ * Validate screenshot request body
+ * @param {Object} body - Request body
+ * @returns {{ valid: boolean, error: string|null }}
+ */
+export function validateScreenshotRequest(body) {
+  if (!body?.name || !body?.image) {
+    return {
+      valid: false,
+      error: 'name and image are required'
+    };
+  }
+  return {
+    valid: true,
+    error: null
+  };
 }

package/dist/{init/agents.js → domains/setup/agent-setup.js}

@@ -1,11 +1,10 @@
 import { createHash } from 'node:crypto';
 import { readdir } from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { readOptionalFile } from '../utils/config-discovery.js';
-import { fileChange } from '../utils/file-changes.js';
-import { getPackageVersion } from '../utils/package-info.js';
-let sourcePath = fileURLToPath(new URL('../../skills/vizzly/', import.meta.url));
+import { fileChange } from '../../shared/file-changes.js';
+import { readOptionalFile } from '../../shared/files.js';
+import { getPackageRoot, getPackageVersion } from '../../shared/package-info.js';
+let sourcePath = path.join(getPackageRoot(), 'skills', 'vizzly');
 let start = '<!-- vizzly-agent-guidance -->';
 let end = '<!-- /vizzly-agent-guidance -->';
 export function agentGuidancePath(cwd) {

package/dist/{commands/init.js → domains/setup/init.commands.js}

@@ -1,24 +1,11 @@
-import { spawn } from 'node:child_process';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { planAgentSetup } from '../init/agents.js';
-import { planConfig } from '../init/core.js';
-import { createPrompts } from '../init/prompts.js';
-import { discoverConfig } from '../utils/config-discovery.js';
-import { applyChanges } from '../utils/file-changes.js';
-import * as output from '../utils/output.js';
-import { projectLinkCommand, validateProjectLinkOptions } from './project.js';
-function runProcess(command, args) {
-  return new Promise((resolve, reject) => {
-    let child = spawn(command, args, {
-      stdio: 'inherit'
-    });
-    child.once('error', reject);
-    child.once('close', (code, signal) => {
-      if (code === 0) resolve();else reject(new Error(`${command} did not finish successfully (${signal || code}).`));
-    });
-  });
-}
+import { applyChanges } from '../../shared/file-changes.js';
+import * as output from '../../shared/output.js';
+import { discoverConfig } from '../config/config-discovery.js';
+import { planConfig } from '../config/config-plan.js';
+import { validateProjectLinkOptions } from '../projects/project.validations.js';
+import { planAgentSetup } from './agent-setup.js';
+import { createPrompts } from './setup-prompts.js';
 async function guidedPlan(cwd, config, prompts) {
   output.hint(`Project: ${cwd}`);
   let guidance = await prompts.confirm('Add the Vizzly skill and AGENTS.md instructions?');
@@ -57,26 +44,6 @@ function agentOptions(options) {
     skill: guidance || !options.skipAgentSkill && Boolean(options.agentSkill)
   };
 }
-async function connectProject(project, options) {
-  let exitCode = 0;
-  let link = () => projectLinkCommand(project, {}, options, {
-    exit: code => {
-      exitCode = code;
-    }
-  });
-  let result = await link();
-  if (result?.reason === 'auth_required') {
-    let cli = fileURLToPath(new URL('../cli.js', import.meta.url));
-    await runProcess(process.execPath, [cli, 'login']);
-    result = await link();
-  }
-  let status = result?.linked ? 'linked' : 'failed';
-  if (!result?.linked && exitCode === 1) status = 'auth_required';
-  return {
-    status,
-    project
-  };
-}
 function showResult(result, json) {
   if (json) {
     output.data(result);
@@ -94,7 +61,9 @@ function showResult(result, json) {
     output.hint('Use a Vizzly client to add screenshot capture.');
   }
 }
-export async function init(options = {}) {
+export async function init(options = {}, {
+  connectProject
+} = {}) {
   output.configure({
     json: options.json || false,
     verbose: options.verbose,