@vizzly-testing/cli 0.5.0 → 0.7.0

package/dist/utils/security.js

@@ -0,0 +1,154 @@
+/**
+ * Security utilities for path sanitization and validation
+ * Protects against path traversal attacks and ensures safe file operations
+ */
+
+import { resolve, normalize, isAbsolute, join } from 'path';
+import { createServiceLogger } from './logger-factory.js';
+const logger = createServiceLogger('SECURITY');
+
+/**
+ * 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)
+ * @returns {string} Sanitized screenshot name
+ */
+export function sanitizeScreenshotName(name, maxLength = 255) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('Screenshot name must be a non-empty string');
+  }
+  if (name.length > maxLength) {
+    throw new Error(`Screenshot name exceeds maximum length of ${maxLength} characters`);
+  }
+
+  // Block directory traversal patterns
+  if (name.includes('..') || name.includes('/') || name.includes('\\')) {
+    throw new Error('Screenshot name contains invalid path characters');
+  }
+
+  // Block absolute paths
+  if (isAbsolute(name)) {
+    throw new Error('Screenshot name cannot be an absolute path');
+  }
+
+  // Allow only safe characters: alphanumeric, hyphens, underscores, and dots
+  // Replace other characters with underscores
+  let sanitized = name.replace(/[^a-zA-Z0-9._-]/g, '_');
+
+  // Prevent names that start with dots (hidden files)
+  if (sanitized.startsWith('.')) {
+    sanitized = 'file_' + sanitized;
+  }
+
+  // Ensure we have a valid filename
+  if (sanitized.length === 0 || sanitized === '.' || sanitized === '..') {
+    sanitized = 'unnamed_screenshot';
+  }
+  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
+  let resolvedWorkingDir = resolve(normalize(workingDir));
+  let resolvedTargetPath = resolve(normalize(targetPath));
+
+  // Ensure the target path starts with the working directory
+  if (!resolvedTargetPath.startsWith(resolvedWorkingDir)) {
+    logger.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
+  let 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;
+  });
+  let targetPath = join(workingDir, ...sanitizedSegments);
+  return validatePathSecurity(targetPath, workingDir);
+}
+
+/**
+ * Validates screenshot properties object for safe values
+ * @param {Object} properties - Properties to validate
+ * @returns {Object} Validated properties object
+ */
+export function validateScreenshotProperties(properties = {}) {
+  if (properties === null || typeof properties !== 'object') {
+    return {};
+  }
+  let validated = {};
+
+  // Validate common properties with safe constraints
+  if (properties.browser && typeof properties.browser === 'string') {
+    try {
+      validated.browser = sanitizeScreenshotName(properties.browser, 50);
+    } catch (error) {
+      // Skip invalid browser names, don't include them
+      logger.warn(`Invalid browser name '${properties.browser}': ${error.message}`);
+    }
+  }
+  if (properties.viewport && typeof properties.viewport === 'object') {
+    let viewport = {};
+    if (typeof properties.viewport.width === 'number' && properties.viewport.width > 0 && properties.viewport.width <= 10000) {
+      viewport.width = Math.floor(properties.viewport.width);
+    }
+    if (typeof properties.viewport.height === 'number' && properties.viewport.height > 0 && properties.viewport.height <= 10000) {
+      viewport.height = Math.floor(properties.viewport.height);
+    }
+    if (Object.keys(viewport).length > 0) {
+      validated.viewport = viewport;
+    }
+  }
+
+  // Allow other safe string properties but sanitize them
+  for (let [key, value] of Object.entries(properties)) {
+    if (key === 'browser' || key === 'viewport') continue; // Already handled
+
+    if (typeof key === 'string' && key.length <= 50 && /^[a-zA-Z0-9_-]+$/.test(key)) {
+      if (typeof value === 'string' && value.length <= 200) {
+        // Store sanitized version of string values
+        validated[key] = value.replace(/[<>&"']/g, ''); // Basic HTML entity prevention
+      } else if (typeof value === 'number' && !isNaN(value) && isFinite(value)) {
+        validated[key] = value;
+      } else if (typeof value === 'boolean') {
+        validated[key] = value;
+      }
+    }
+  }
+  return validated;
+}

package/docs/api-reference.md

@@ -289,6 +289,7 @@ Upload screenshots from a directory.
 - `--token <token>` - API token override
 - `--wait` - Wait for build completion
 - `--upload-all` - Upload all screenshots without SHA deduplication
+- `--parallel-id <id>` - Unique identifier for parallel test execution
 
 **Exit Codes:**
 - `0` - Success (all approved or no changes)
@@ -321,6 +322,9 @@ Run tests with Vizzly integration.
 - `--upload-timeout <ms>` - Upload wait timeout in ms (default: from config or 30000)
 - `--upload-all` - Upload all screenshots without SHA deduplication
 
+*Parallel Execution:*
+- `--parallel-id <id>` - Unique identifier for parallel test execution
+
 *Development & Testing:*
 - `--allow-no-token` - Allow running without API token
 - `--token <token>` - API token override
@@ -403,6 +407,26 @@ Check build status.
 - `1` - Build has changes requiring review
 - `2` - Build failed or error
 
+### `vizzly finalize <parallel-id>`
+
+Finalize a parallel build after all shards complete.
+
+**Arguments:**
+- `<parallel-id>` - Parallel ID to finalize
+
+**Description:**
+When using parallel execution with `--parallel-id`, all test shards contribute screenshots to the same shared build. After all shards complete successfully, use this command to finalize the build and trigger comparison processing.
+
+**Example:**
+```bash
+# After all parallel shards complete
+vizzly finalize "ci-run-123-attempt-1"
+```
+
+**Exit Codes:**
+- `0` - Build finalized successfully
+- `1` - Finalization failed or error
+
 ### `vizzly doctor`
 
 Run environment diagnostics.
@@ -486,6 +510,9 @@ Configuration loaded via cosmiconfig in this order:
 - `VIZZLY_API_URL` - API base URL override
 - `VIZZLY_LOG_LEVEL` - Logger level (`debug`, `info`, `warn`, `error`)
 
+**Parallel Builds:**
+- `VIZZLY_PARALLEL_ID` - Unique identifier for parallel test execution
+
 **Git Information Override (CI/CD Enhancement):**
 - `VIZZLY_COMMIT_SHA` - Override detected commit SHA
 - `VIZZLY_COMMIT_MESSAGE` - Override detected commit message

package/docs/tdd-mode.md

@@ -8,7 +8,7 @@ TDD Mode transforms your visual testing workflow by:
 
 - **Local comparison** - Compares screenshots on your machine using `odiff`
 - **Fast feedback** - No network uploads during development
-- **Immediate results** - Tests fail instantly when visual differences are detected  
+- **Immediate results** - Tests fail instantly when visual differences are detected
 - **Auto-baseline creation** - Creates baselines locally when none exist
 - **No token required** - Works entirely offline for local development
 
@@ -43,7 +43,7 @@ npx vizzly tdd "npm test"
 🐻 **Comparison behavior:**
 - Compares new screenshots against local baselines
 - **Tests fail immediately** when visual differences detected
-- Shows exact diff paths and percentages
+- Generates interactive HTML report for visual analysis
 - Creates diff images in `.vizzly/diffs/`
 
 ### 3. Accept Changes (Update Baseline)
@@ -56,7 +56,7 @@ npx vizzly tdd "npm test" --set-baseline
 
 🐻 **Baseline update behavior:**
 - Skips all comparisons
-- Sets current screenshots as new baselines  
+- Sets current screenshots as new baselines
 - All tests pass (baseline accepted)
 - Future runs use updated baselines
 
@@ -73,7 +73,7 @@ npx vizzly run "npm test" --wait
 TDD Mode creates a local development environment:
 
 1. **Downloads baselines** - Gets approved screenshots from Vizzly
-2. **Runs tests** - Executes your test suite normally  
+2. **Runs tests** - Executes your test suite normally
 3. **Captures screenshots** - Collects new screenshots via `vizzlyScreenshot()`
 4. **Compares locally** - Uses `odiff` for pixel-perfect comparison
 5. **Fails immediately** - Tests fail when differences exceed threshold
@@ -89,9 +89,11 @@ TDD Mode creates a `.vizzly/` directory:
 │   ├── homepage.png
 │   ├── dashboard.png
 │   └── metadata.json    # Baseline build information
-├── current/             # Current test screenshots  
+├── current/             # Current test screenshots
 │   ├── homepage.png
 │   └── dashboard.png
+├── report/              # Interactive HTML report
+│   └── index.html       # Visual comparison interface
 └── diffs/               # Visual diff images (when differences found)
     ├── homepage.png     # Red overlay showing differences
     └── dashboard.png
@@ -99,6 +101,50 @@ TDD Mode creates a `.vizzly/` directory:
 
 **Important**: Add `.vizzly/` to your `.gitignore` file as it contains local development artifacts.
 
+## Interactive HTML Report
+
+Each TDD run automatically generates a comprehensive HTML report at `.vizzly/report/index.html`. This report provides advanced visual comparison tools to analyze differences:
+
+### 🐻 **Viewing Modes**
+
+**Overlay Mode** (Default)
+- Shows current screenshot as base layer
+- Click to toggle diff overlay on/off
+- Perfect for spotting subtle changes
+
+**Side-by-Side Mode**
+- Displays baseline and current screenshots horizontally
+- Easy to compare layout and content changes
+- Great for reviewing larger modifications
+
+**Onion Skin Mode**
+- Drag across image to reveal baseline underneath
+- Interactive reveal lets you control comparison area
+- Ideal for precise change inspection
+
+**Toggle Mode**
+- Click image to switch between baseline and current
+- Quick back-and-forth comparison
+- Simple way to see before/after
+
+### 🐻 **Report Features**
+
+- **Dark Theme** - Easy on the eyes during long debugging sessions
+- **Mobile Responsive** - Works on any screen size
+- **Clickable File Paths** - Click from terminal to open instantly
+- **Clean Status Display** - Shows "Visual differences detected" instead of technical metrics
+- **Test Summary** - Total, passed, failed counts and pass rate
+
+### 🐻 **Opening the Report**
+
+```bash
+# Report path is shown after each run
+🐻 View detailed report: file:///path/to/.vizzly/report/index.html
+
+# Click the link in your terminal, or open manually
+open .vizzly/report/index.html  # macOS
+```
+
 ## Command Options
 
 ### Basic TDD Mode
@@ -122,7 +168,7 @@ vizzly tdd "npm test" --set-baseline
 VIZZLY_TOKEN=your-token vizzly tdd "npm test" --baseline-build build-abc123
 ```
 
-**`--baseline-comparison <id>`** - Use specific comparison as baseline  
+**`--baseline-comparison <id>`** - Use specific comparison as baseline
 ```bash
 VIZZLY_TOKEN=your-token vizzly tdd "npm test" --baseline-comparison comparison-xyz789
 ```
@@ -272,14 +318,14 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
       - run: npm ci
-      
+
       # Use TDD mode for PR builds (faster, no uploads)
       - name: TDD Visual Tests (PR)
         if: github.event_name == 'pull_request'
         run: npx vizzly tdd "npm test"
         env:
           VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
-      
+
       # Upload full build for main branch
       - name: Full Visual Tests (main)
         if: github.ref == 'refs/heads/main'
@@ -295,7 +341,7 @@ jobs:
 - **Immediate feedback** - See results in seconds
 - **No API rate limits** - Test as often as needed
 
-### Development Experience  
+### Development Experience
 - **Fast iteration** - Make changes and test immediately
 - **Visual debugging** - See exact pixel differences
 - **Offline capable** - Works without internet (after initial baseline download)
@@ -354,7 +400,7 @@ npm install odiff-bin
 
 ### Use TDD Mode For
 - **Local development** - Fast iteration on UI changes
-- **Bug fixing** - Verify visual fixes immediately  
+- **Bug fixing** - Verify visual fixes immediately
 - **PR validation** - Quick checks without uploading
 - **Debugging** - Understand exactly what changed visually
 
@@ -372,5 +418,5 @@ npm install odiff-bin
 ## Next Steps
 
 - Learn about [Test Integration](./test-integration.md) for screenshot capture
-- Explore [Upload Command](./upload-command.md) for direct uploads  
-- Check the [API Reference](./api-reference.md) for programmatic usage
+- Explore [Upload Command](./upload-command.md) for direct uploads
+- Check the [API Reference](./api-reference.md) for programmatic usage

package/docs/test-integration.md

@@ -209,6 +209,15 @@ vizzly run "npm test" --upload-all
 vizzly run "npm test" --threshold 0.02
 ```
 
+### Parallel Execution
+
+**`--parallel-id <id>`** - Unique identifier for parallel test execution
+```bash
+vizzly run "npm test" --parallel-id "ci-run-123"
+```
+
+When using parallel execution, multiple test runners can contribute screenshots to the same build. This is particularly useful for CI/CD pipelines with parallel jobs.
+
 ### Development Options
 
 For TDD mode, use the dedicated `vizzly tdd` command. See [TDD Mode Guide](./tdd-mode.md) for details.
@@ -283,6 +292,43 @@ jobs:
 
 **Enhanced Git Information:** The `VIZZLY_*` environment variables ensure accurate git metadata is captured in your builds, avoiding issues with merge commits that can occur in CI environments.
 
+### Parallel Builds in CI
+
+For parallel test execution, use `--parallel-id` to ensure all shards contribute to the same build:
+
+```yaml
+# GitHub Actions with parallel matrix
+jobs:
+  e2e-tests:
+    strategy:
+      matrix:
+        shard: [1/4, 2/4, 3/4, 4/4]
+    steps:
+      - name: Run tests with Vizzly
+        run: |
+          npx vizzly run "npm test -- --shard=${{ matrix.shard }}" \
+            --parallel-id="${{ github.run_id }}-${{ github.run_attempt }}"
+        env:
+          VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
+
+  finalize-e2e:
+    needs: e2e-tests
+    runs-on: ubuntu-latest
+    if: always() && needs.e2e-tests.result == 'success'
+    steps:
+      - name: Finalize parallel build
+        run: |
+          npx vizzly finalize "${{ github.run_id }}-${{ github.run_attempt }}"
+        env:
+          VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
+```
+
+**How Parallel Builds Work:**
+1. All shards with the same `--parallel-id` contribute to one shared build
+2. First shard creates the build, subsequent shards add screenshots to it
+3. After all shards complete, use `vizzly finalize` to trigger comparison processing
+4. Use GitHub's run ID + attempt for uniqueness across workflow runs
+
 ### GitLab CI
 
 ```yaml
@@ -294,6 +340,29 @@ visual-tests:
     - npx vizzly run "npm test" --wait
   variables:
     VIZZLY_TOKEN: $VIZZLY_TOKEN
+
+# Parallel execution example
+visual-tests-parallel:
+  stage: test
+  parallel:
+    matrix:
+      - SHARD: "1/4"
+      - SHARD: "2/4"
+      - SHARD: "3/4"
+      - SHARD: "4/4"
+  script:
+    - npm ci
+    - npx vizzly run "npm test -- --shard=$SHARD" --parallel-id "$CI_PIPELINE_ID-$CI_JOB_ID"
+  variables:
+    VIZZLY_TOKEN: $VIZZLY_TOKEN
+
+finalize-visual-tests:
+  stage: finalize
+  needs: ["visual-tests-parallel"]
+  script:
+    - npx vizzly finalize "$CI_PIPELINE_ID-$CI_JOB_ID"
+  variables:
+    VIZZLY_TOKEN: $VIZZLY_TOKEN
 ```
 
 ## Advanced Usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -53,9 +53,10 @@
   ],
   "scripts": {
     "start": "node src/index.js",
-    "build": "npm run clean && npm run compile && npm run types",
+    "build": "npm run clean && npm run compile && npm run copy-assets && npm run types",
     "clean": "rimraf dist",
     "compile": "babel src --out-dir dist --ignore '**/*.test.js'",
+    "copy-assets": "cp src/services/report-generator/report.css dist/services/report-generator/",
     "types": "tsc --emitDeclarationOnly --outDir dist/types",
     "prepublishOnly": "npm test && npm run build",
     "test": "vitest run",