@percy/core 1.31.14-beta.1 → 1.31.14-beta.2

package/dist/archive.js

@@ -0,0 +1,117 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+const ARCHIVE_VERSION = 1;
+const MAX_FILENAME_LENGTH = 200;
+const UNSAFE_CHARS = /[/\\:*?"<>|]/g;
+
+// Validates the archive dir to prevent path traversal attacks.
+// Returns the resolved absolute path.
+export function validateArchiveDir(archiveDir) {
+  let resolved = path.resolve(archiveDir);
+  let normalized = path.normalize(resolved);
+
+  // Reject if the normalized path still contains '..' segments
+  if (normalized.split(path.sep).includes('..')) {
+    throw new Error(`Invalid archive dir: path traversal detected in "${archiveDir}"`);
+  }
+  return resolved;
+}
+
+// Sanitizes a snapshot name into a safe filename.
+// Strips unsafe characters and appends a hash to prevent collisions.
+export function sanitizeFilename(name) {
+  let safe = name.replace(UNSAFE_CHARS, '_');
+  if (safe.length > MAX_FILENAME_LENGTH) {
+    safe = safe.substring(0, MAX_FILENAME_LENGTH);
+  }
+
+  // Append a short hash of the original name for collision prevention
+  let hash = crypto.createHash('sha256').update(name).digest('hex').substring(0, 8);
+  return `${safe}-${hash}`;
+}
+
+// Serializes a snapshot into a JSON-safe object for archiving.
+// Resources have their binary content base64-encoded.
+export function serializeSnapshot(snapshot) {
+  let {
+    resources,
+    ...snapshotData
+  } = snapshot;
+  return {
+    version: ARCHIVE_VERSION,
+    snapshot: snapshotData,
+    resources: (resources || []).map(r => ({
+      ...r,
+      content: r.content ? Buffer.from(r.content).toString('base64') : null
+    }))
+  };
+}
+
+// Validates and deserializes an archived snapshot from parsed JSON.
+// Decodes base64 resource content back to Buffers.
+export function deserializeSnapshot(data) {
+  if (!data || typeof data !== 'object') {
+    throw new Error('Invalid archive: expected an object');
+  }
+  if (data.version !== ARCHIVE_VERSION) {
+    throw new Error(`Unsupported archive version: ${data.version} (expected ${ARCHIVE_VERSION})`);
+  }
+  if (!data.snapshot || typeof data.snapshot.name !== 'string' || !data.snapshot.name) {
+    throw new Error('Invalid archive: missing snapshot name');
+  }
+  if (!Array.isArray(data.resources) || data.resources.length === 0) {
+    throw new Error('Invalid archive: missing or empty resources');
+  }
+  return {
+    ...data.snapshot,
+    resources: data.resources.map(r => ({
+      ...r,
+      content: r.content ? Buffer.from(r.content, 'base64') : null
+    }))
+  };
+}
+
+// Archives a single snapshot to the archive directory.
+// Creates the directory if it doesn't exist.
+export function archiveSnapshot(archiveDir, snapshot) {
+  fs.mkdirSync(archiveDir, {
+    recursive: true
+  });
+  let filename = sanitizeFilename(snapshot.name);
+  let filepath = path.join(archiveDir, `${filename}.json`);
+  let serialized = serializeSnapshot(snapshot);
+  fs.writeFileSync(filepath, JSON.stringify(serialized));
+}
+
+// Reads all archived snapshots from the given directory.
+// Skips symlinks and invalid files with warnings.
+export function readArchivedSnapshots(archiveDir, log) {
+  let resolved = validateArchiveDir(archiveDir);
+  if (!fs.existsSync(resolved) || !fs.lstatSync(resolved).isDirectory()) {
+    throw new Error(`Archive directory not found: ${archiveDir}`);
+  }
+  let entries = fs.readdirSync(resolved);
+  let snapshots = [];
+  for (let entry of entries) {
+    if (!entry.endsWith('.json')) continue;
+    let filepath = path.join(resolved, entry);
+    let stat = fs.lstatSync(filepath);
+
+    // Skip symlinks for security
+    if (stat.isSymbolicLink()) {
+      log === null || log === void 0 || log.warn(`Skipping symlink: ${entry}`);
+      continue;
+    }
+    if (!stat.isFile()) continue;
+    try {
+      let raw = fs.readFileSync(filepath, 'utf-8');
+      let data = JSON.parse(raw);
+      let snapshot = deserializeSnapshot(data);
+      snapshots.push(snapshot);
+    } catch (error) {
+      log === null || log === void 0 || log.warn(`Skipping invalid archive file "${entry}": ${error.message}`);
+    }
+  }
+  return snapshots;
+}

package/dist/config.js

@@ -7,6 +7,9 @@ export const configSchema = {
       deferUploads: {
         type: 'boolean'
       },
+      archiveDir: {
+        type: 'string'
+      },
       useSystemProxy: {
         type: 'boolean',
         default: false

package/dist/percy.js

@@ -43,6 +43,8 @@ export class Percy {
   constructor({
     // initial log level
     loglevel,
+    // path to save snapshot data to disk
+    archiveDir,
     // process uploads before the next snapshot
     delayUploads,
     // process uploads after all snapshots
@@ -83,6 +85,7 @@ export class Percy {
     });
     labels ?? (labels = (_config$percy = config.percy) === null || _config$percy === void 0 ? void 0 : _config$percy.labels);
     deferUploads ?? (deferUploads = (_config$percy2 = config.percy) === null || _config$percy2 === void 0 ? void 0 : _config$percy2.deferUploads);
+    if (archiveDir) skipUploads = skipUploads != null ? skipUploads : true;
     this.config = config;
     this.cliStartTime = null;
     if (testing) loglevel = 'silent';
@@ -95,6 +98,7 @@ export class Percy {
     this.skipDiscovery = this.dryRun || !!skipDiscovery;
     this.delayUploads = this.skipUploads || !!delayUploads;
     this.deferUploads = this.skipUploads || !!deferUploads;
+    this.archiveDir = this.skipUploads && archiveDir ? archiveDir : null;
     this.labels = labels;
     this.suggestionsCallCounter = suggestionsCallCounter;
     this.client = new PercyClient({
@@ -132,7 +136,7 @@ export class Percy {
     };
 
     // generator methods are wrapped to autorun and return promises
-    for (let m of ['start', 'stop', 'flush', 'idle', 'snapshot', 'upload']) {
+    for (let m of ['start', 'stop', 'flush', 'idle', 'snapshot', 'upload', 'replaySnapshot']) {
       // the original generator can be referenced with percy.yield.<method>
       let method = (this.yield || (this.yield = {}))[m] = this[m].bind(this);
       this[m] = (...args) => generatePromise(method(...args));
@@ -259,6 +263,15 @@ export class Percy {
         await this.loadAutoConfiguredHostnames();
       }
 
+      // validate and log archive dir if configured
+      if (this.archiveDir) {
+        let {
+          validateArchiveDir
+        } = await import('./archive.js');
+        this.archiveDir = validateArchiveDir(this.archiveDir);
+        this.log.info(`Archiving snapshots to: ${this.archiveDir}`);
+      }
+
       // start the snapshots queue immediately when not delayed or deferred
       if (!this.delayUploads && !this.deferUploads) yield _classPrivateFieldGet(_snapshots, this).start();
       // do not start the discovery queue when not needed
@@ -400,6 +413,11 @@ export class Percy {
         this.log.info(info('Found', _classPrivateFieldGet(_snapshots, this).size));
       }
 
+      // log archive summary
+      if (this.archiveDir && _classPrivateFieldGet(_snapshots, this).size) {
+        this.log.info(`Archived ${_classPrivateFieldGet(_snapshots, this).size} snapshot(s) to: ${this.archiveDir}`);
+      }
+
       // Save domain validation config before closing
       if (!this.skipUploads && !this.skipDiscovery) {
         await this.saveHostnamesToAutoConfigure();
@@ -611,6 +629,17 @@ export class Percy {
             config: this.config
           })
         }, snapshot => {
+          // archive snapshot to disk if configured
+          if (this.archiveDir) {
+            import('./archive.js').then(({
+              archiveSnapshot
+            }) => {
+              archiveSnapshot(this.archiveDir, snapshot);
+            }).catch(err => {
+              this.log.error(`Failed to archive snapshot "${snapshot.name}": ${err.message}`);
+            });
+          }
+
           // attaching promise resolve reject so to wait for snapshot to complete
           if (this.syncMode(snapshot)) {
             snapshotPromise[snapshot.name] = new Promise((resolve, reject) => {
@@ -700,6 +729,25 @@ export class Percy {
       }
     }.call(this);
   }
+
+  // Pushes a pre-built snapshot directly to the upload queue without discovery.
+  // Used by the replay command to upload previously archived snapshots.
+  *replaySnapshot(snapshot) {
+    var _this$build4;
+    if (this.readyState !== 1) {
+      throw new Error('Not running');
+    } else if ((_this$build4 = this.build) !== null && _this$build4 !== void 0 && _this$build4.error) {
+      throw new Error(this.build.error);
+    }
+    snapshot.meta = {
+      snapshot: {
+        name: snapshot.name,
+        testCase: snapshot.testCase
+      }
+    };
+    this.log.info(`Replaying snapshot: ${snapshot.name}`, snapshot.meta);
+    _classPrivateFieldGet(_snapshots, this).push(snapshot);
+  }
   shouldSkipAssetDiscovery(tokenType) {
     if (this.testing && JSON.stringify(this.testing) === JSON.stringify({})) {
       return true;
@@ -780,7 +828,7 @@ export class Percy {
   async sendBuildLogs() {
     if (!process.env.PERCY_TOKEN) return;
     try {
-      var _this$build4, _this$build5, _this$build6, _this$build7;
+      var _this$build5, _this$build6, _this$build7, _this$build8;
       const logsObject = {
         clilogs: logger.query(log => !['ci'].includes(log.debug))
       };
@@ -792,10 +840,10 @@ export class Percy {
         logsObject.cilogs = redactedContent;
       }
       const content = base64encode(Pako.gzip(JSON.stringify(logsObject)));
-      const referenceId = (_this$build4 = this.build) !== null && _this$build4 !== void 0 && _this$build4.id ? `build_${(_this$build5 = this.build) === null || _this$build5 === void 0 ? void 0 : _this$build5.id}` : (_this$build6 = this.build) === null || _this$build6 === void 0 ? void 0 : _this$build6.id;
+      const referenceId = (_this$build5 = this.build) !== null && _this$build5 !== void 0 && _this$build5.id ? `build_${(_this$build6 = this.build) === null || _this$build6 === void 0 ? void 0 : _this$build6.id}` : (_this$build7 = this.build) === null || _this$build7 === void 0 ? void 0 : _this$build7.id;
       const eventObject = {
         content: content,
-        build_id: (_this$build7 = this.build) === null || _this$build7 === void 0 ? void 0 : _this$build7.id,
+        build_id: (_this$build8 = this.build) === null || _this$build8 === void 0 ? void 0 : _this$build8.id,
         reference_id: referenceId,
         service_name: 'cli',
         base64encoded: true
@@ -868,9 +916,9 @@ export class Percy {
     const newAllowedDomains = Array.from(processedHosts).filter(domain => !autoConfiguredHosts.has(domain));
     const hasNewDomains = newAllowedDomains.length > 0 || newErrorHosts.size > 0;
     try {
-      var _this$build8;
+      var _this$build9;
       await this.client.updateProjectDomainConfig({
-        buildId: (_this$build8 = this.build) === null || _this$build8 === void 0 ? void 0 : _this$build8.id,
+        buildId: (_this$build9 = this.build) === null || _this$build9 === void 0 ? void 0 : _this$build9.id,
         allowedDomains: Array.from(processedHosts),
         errorDomains: Array.from(newErrorHosts)
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/core",
-  "version": "1.31.14-beta.1",
+  "version": "1.31.14-beta.2",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
     },
     "./utils": "./dist/utils.js",
     "./config": "./dist/config.js",
+    "./archive": "./dist/archive.js",
     "./install": "./dist/install.js",
     "./test/helpers": "./test/helpers/index.js",
     "./test/helpers/server": "./test/helpers/server.js"
@@ -43,12 +44,12 @@
     "test:types": "tsd"
   },
   "dependencies": {
-    "@percy/client": "1.31.14-beta.1",
-    "@percy/config": "1.31.14-beta.1",
-    "@percy/dom": "1.31.14-beta.1",
-    "@percy/logger": "1.31.14-beta.1",
-    "@percy/monitoring": "1.31.14-beta.1",
-    "@percy/webdriver-utils": "1.31.14-beta.1",
+    "@percy/client": "1.31.14-beta.2",
+    "@percy/config": "1.31.14-beta.2",
+    "@percy/dom": "1.31.14-beta.2",
+    "@percy/logger": "1.31.14-beta.2",
+    "@percy/monitoring": "1.31.14-beta.2",
+    "@percy/webdriver-utils": "1.31.14-beta.2",
     "content-disposition": "^0.5.4",
     "cross-spawn": "^7.0.3",
     "extract-zip": "^2.0.1",
@@ -62,7 +63,7 @@
     "yaml": "^2.4.1"
   },
   "optionalDependencies": {
-    "@percy/cli-doctor": "1.31.14-beta.1"
+    "@percy/cli-doctor": "1.31.14-beta.2"
   },
-  "gitHead": "dd6957822cc94d460fd9c043a44cc4c9c5fcba23"
+  "gitHead": "e4fce73023453b77cdef50aac1a9bd5eb70cd01a"
 }