@percy/cli-exec 1.32.5 → 1.32.6-beta.0

package/dist/baseline.js

@@ -0,0 +1,336 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import url from 'url';
+import { createResource, createRootResource } from '@percy/cli-command/utils';
+
+// Drop-in baseline seeding — the `percy exec` side.
+//
+// Provider contract (framework knowledge stays in the SDK package, as with command discovery):
+// any installed Percy SDK can declare
+//
+//   "@percy/cli": { "baselineProvider": "./path/to/module.js" }
+//
+// in its package.json. The module's default export must be:
+//
+//   {
+//     buildSource,            // drop-in source tag for the head build (e.g. 'playwright-dropin')
+//     async discoverBaselines({ cwd, log })
+//       // -> { baselines: [{ filepath, name, browserFamily, width, height }], degraded?, reason? }
+//   }
+//
+// On an empty Percy project, `percy exec` uploads committed baseline screenshots as build #1
+// (auto-approved server-side, the user's suite never runs for it) before starting the head
+// build. On an established project nothing is seeded; the user is pointed at the explicit
+// `percy playwright:setup-baseline` command instead.
+
+// Parallel seed-upload cap: fast on large baseline sets without stampeding the API.
+const SEED_CONCURRENCY = 8;
+const BASELINE_SOURCE = 'playwright-dropin-baseline';
+
+// Path hygiene at the fs boundary: directory-entry names must be single path components (a name
+// containing a separator or dot-segment never comes from an honest readdir) and path strings
+// are NUL-stripped.
+export function sanitizePath(p) {
+  return String(p).replace(/\0/g, '');
+}
+export function sanitizeDirentName(name) {
+  let clean = String(name).replace(/\0/g, '');
+  if (!clean || clean === '.' || clean === '..') return null;
+  if (clean.includes('/') || clean.includes('\\')) return null;
+  return clean;
+}
+
+// Collect @percy/* (and percy-cli-*) package roots from the nearest node_modules — the same
+// semantics as @percy/cli's command-discovery walk (findModulePackages): stop at the FIRST
+// node_modules at or above `dir`, never cross the home directory, and degrade to [] on any
+// filesystem error so discovery can never break `percy exec`.
+function findPercyPackages(dir, log) {
+  try {
+    dir = sanitizePath(dir);
+
+    // not given node_modules or a directory that contains node_modules, look up
+    if (path.basename(dir) !== 'node_modules') {
+      let modulesDir = path.join(dir, 'node_modules');
+      let next = fs.existsSync(modulesDir) ? modulesDir : path.dirname(dir);
+      if (next === dir || next === os.homedir()) return [];
+      return findPercyPackages(next, log);
+    }
+    let found = [];
+    for (let entry of fs.readdirSync(dir)) {
+      let name = sanitizeDirentName(entry);
+      // istanbul ignore next: readdir yields single path components — defense-in-depth only
+      if (name === null) continue;
+      if (name === '@percy') {
+        for (let scopedEntry of fs.readdirSync(path.join(dir, name))) {
+          let scoped = sanitizeDirentName(scopedEntry);
+          // istanbul ignore next: readdir yields single path components — defense-in-depth only
+          if (scoped === null) continue;
+          found.push(path.join(dir, name, scoped));
+        }
+      } else if (name.startsWith('percy-cli-')) {
+        found.push(path.join(dir, name));
+      }
+    }
+    return found;
+  } catch (err) {
+    log === null || log === void 0 || log.debug(`Baseline provider discovery walk failed: ${err.message}`);
+    return [];
+  }
+}
+
+// Find the first installed package declaring a baseline provider and import it. Returns null
+// when none is installed or when the drop-in is disabled (PERCY_DROPIN_DISABLE is the same
+// switch the SDK override honors, so one env var turns off both the matcher and the seeding).
+export async function findBaselineProvider({
+  cwd = process.cwd(),
+  log
+} = {}) {
+  if (process.env.PERCY_DROPIN_DISABLE === 'true') {
+    log === null || log === void 0 || log.debug('Drop-in disabled via PERCY_DROPIN_DISABLE — skipping baseline provider discovery');
+    return null;
+  }
+  for (let pkgPath of findPercyPackages(cwd, log)) {
+    let pkgFile = path.join(sanitizePath(pkgPath), 'package.json');
+    try {
+      var _pkg$PercyCli;
+      if (!fs.existsSync(pkgFile)) continue;
+      let pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+      let providerPath = (_pkg$PercyCli = pkg['@percy/cli']) === null || _pkg$PercyCli === void 0 ? void 0 : _pkg$PercyCli.baselineProvider;
+      if (!providerPath) continue;
+
+      // Confine the provider module to the declaring package — a package.json pointing outside
+      // its own root (../../x.js) is malformed at best and gets skipped.
+      let resolved = path.resolve(sanitizePath(pkgPath), sanitizePath(providerPath));
+      if (!resolved.startsWith(path.resolve(sanitizePath(pkgPath)) + path.sep)) {
+        log === null || log === void 0 || log.debug(`Skipping baseline provider from ${pkgPath}: provider path escapes the package`);
+        continue;
+      }
+      let module = await import(url.pathToFileURL(resolved).href);
+      let provider = module.default || module;
+      if (typeof provider.discoverBaselines === 'function') {
+        return {
+          ...provider,
+          packageName: pkg.name
+        };
+      }
+    } catch (err) {
+      log === null || log === void 0 || log.debug(`Skipping baseline provider from ${pkgPath}: ${err.message}`);
+    }
+  }
+  return null;
+}
+
+// The seed build keeps processing (renders + auto-approval) after finalize. The head build must
+// not start until it reaches a terminal state — head snapshots select their baseline as they are
+// processed, and an unapproved seed means the whole first run shows as new instead of diffing.
+// The timeout matches the pipeline latency budget (~99% of builds finish under 5 minutes) —
+// a seed of committed screenshots still renders server-side, so first runs can hold for minutes.
+export async function waitForSeedBuild(client, buildId, {
+  log,
+  timeout = 600000,
+  interval = 5000
+}) {
+  let deadline = Date.now() + timeout;
+  let state = 'pending';
+  let polls = 0;
+  for (;;) {
+    ({
+      state
+    } = (await client.getBuild(buildId)).data.attributes);
+    if (state !== 'pending' && state !== 'processing') return state;
+    if (Date.now() >= deadline) return state;
+    // A visible heartbeat every ~30s so a multi-minute first-run hold doesn't look like a hang.
+    log[polls++ % 6 === 0 ? 'info' : 'debug'](`Baseline build still ${state} — waiting for it to finish before tests start`);
+    await new Promise(resolve => setTimeout(resolve, interval));
+  }
+}
+
+// Establish the project's baseline from committed screenshots BEFORE the head build starts.
+// Never throws — a seeding problem must not break `percy exec`. Returns true when a baseline
+// build was created and finalized.
+export async function maybeSeedBaseline(percy, provider, {
+  log,
+  waitTimeout,
+  waitInterval
+}) {
+  try {
+    var _res$data, _res$data$attributes;
+    // Percy on Automate captures happen on the remote BrowserStack browser — committed local
+    // screenshots can never pair with those comparisons, so there is nothing to seed; the
+    // project's baseline is established by its first run instead.
+    if (percy.projectType === 'automate') {
+      log.debug('Automate project — baseline seeding does not apply (the first run establishes the baseline)');
+      return false;
+    }
+
+    // Parallel shards would race each other seeding; the head build dedup doesn't apply to the
+    // separate seed build, so leave parallel runs to the explicit setup command.
+    if (process.env.PERCY_PARALLEL_TOTAL) {
+      log.debug('Skipping baseline seeding for a parallel build');
+      return false;
+    }
+    let {
+      baselines = [],
+      degraded,
+      reason
+    } = (await provider.discoverBaselines({
+      cwd: process.cwd(),
+      log
+    })) || {};
+    if (degraded) {
+      log.debug(`Baseline discovery degraded (${reason}) — nothing seeded`);
+      return false;
+    }
+    // A provider yielding sparse/null entries must not wedge the upload workers.
+    baselines = baselines.filter(Boolean);
+    if (!baselines.length) return false;
+
+    // First-ness is decided by the API, never locally: on an established project it answers
+    // with the baseline-skipped sentinel (no build persisted), on an empty project it creates
+    // build #1 as the baseline.
+    let res = await percy.client.createBuild({
+      projectType: percy.projectType,
+      source: BASELINE_SOURCE,
+      dropinBaselineCandidate: true
+    });
+
+    // Compat guard for APIs that predate the candidate attribute (which decide first-ness
+    // server-side): only ever seed build #1 — an old API ignores the attribute and hands back
+    // a NORMAL build, so anything past #1 abandons the build unused and points at the explicit
+    // setup command (which works at any build number) instead of polluting history.
+    if (!(res !== null && res !== void 0 && (_res$data = res.data) !== null && _res$data !== void 0 && _res$data.id) || ((_res$data$attributes = res.data.attributes) === null || _res$data$attributes === void 0 ? void 0 : _res$data$attributes['build-number']) !== 1) {
+      log.info(`Found ${baselines.length} committed baseline snapshot(s), but this project ` + 'already has builds — to (re)establish the baseline from them, run: ' + 'npx percy playwright:setup-baseline');
+      return false;
+    }
+    let buildId = res.data.id;
+    log.info(`New Percy project with ${baselines.length} committed baseline snapshot(s) ` + 'detected — establishing your baseline (build #1) before running tests');
+    let seeded = await uploadBaselines(percy.client, buildId, baselines, {
+      log,
+      projectType: percy.projectType
+    });
+
+    // Nothing uploaded (e.g. a transient network failure across the board): do NOT finalize —
+    // an empty auto-approved build #1 would establish the project with a blank baseline and
+    // permanently disable the auto-seed path. The unfinalized build expires server-side.
+    if (seeded === 0) {
+      log.warn(`Could not upload any of the ${baselines.length} committed baseline snapshot(s) — ` + 'baseline not established. Once connectivity recovers, run: ' + 'npx percy playwright:setup-baseline');
+      return false;
+    }
+    await percy.client.finalizeBuild(buildId);
+    let state;
+    try {
+      state = await waitForSeedBuild(percy.client, buildId, {
+        log,
+        timeout: waitTimeout,
+        interval: waitInterval
+      });
+    } catch (err) {
+      log.debug(`Baseline build wait failed: ${err.message}`);
+    }
+    if (state === 'finished') {
+      log.info(`Baseline established from ${seeded}/${baselines.length} committed snapshot(s) ` + 'and auto-approved — this run diffs against it.');
+    } else {
+      log.warn(`Baseline build did not finish processing in time (state: ${state || 'unknown'}) — ` + 'snapshots in this run may show as new instead of diffing against the baseline');
+    }
+    return true;
+  } catch (err) {
+    log.warn('Skipping baseline setup');
+    log.debug(err.message);
+    return false;
+  }
+}
+
+// Clamp a pixel dimension to the API's accepted snapshot range (same as `percy upload`).
+function clampDimension(value, fallback) {
+  return Math.max(10, Math.min(value || fallback, 2000));
+}
+
+// A committed baseline PNG becomes a WEB snapshot: a generated root DOM displaying the image at
+// its native size plus the image resource — the exact shape `percy upload` uses for web projects,
+// so Percy renders the baseline in the project's own browsers and it pairs with the head run's
+// DOM snapshots by (name, browser, width).
+async function imageSnapshotResources({
+  name,
+  filepath,
+  width,
+  height
+}) {
+  let rootUrl = `http://local/${encodeURIComponent(name)}`;
+  let imageUrl = `http://local/${encodeURIComponent(name)}.png`;
+  let content = await fs.promises.readFile(filepath);
+  return [createRootResource(rootUrl, `
+      <!doctype html>
+      <html lang="en">
+        <head>
+          <meta charset="utf-8">
+          <title>${name}</title>
+          <style>
+            *, *::before, *::after { margin: 0; padding: 0; font-size: 0; }
+            html, body { width: 100%; }
+            img { max-width: 100%; }
+          </style>
+        </head>
+        <body>
+          <img src="${imageUrl}" width="${width}px" height="${height}px"/>
+        </body>
+      </html>
+    `), createResource(imageUrl, content, 'image/png')];
+}
+
+// Bounded-concurrency upload of committed baseline files into `buildId`, shaped by project type:
+//   • web — each PNG becomes a rendered WEB SNAPSHOT (root DOM + image resource); web projects
+//     reject bare comparison tiles ("root resource" validation), and rendering server-side makes
+//     the baseline pair with the head run's DOM snapshots.
+//   • app — each PNG uploads straight through the COMPARISON ingest (tag + tile); no render flow
+//     is triggered, exactly how App Percy ingests screenshots. The tag width is the identity
+//     width (project viewport) so it pairs with the head run's uploads; height comes from the
+//     PNG bytes.
+// Per-file failures are skipped (a partial baseline beats none) and reported in the count.
+export async function uploadBaselines(client, buildId, baselines, {
+  log,
+  projectType = 'web'
+}) {
+  let queue = [...baselines];
+  let seeded = 0;
+  let uploadOne = async b => {
+    if (projectType === 'app') {
+      await client.sendComparison(buildId, {
+        name: b.name,
+        // Mirror the drop-in SDK's tag shape exactly (incl. browserName) — comparison pairing
+        // matches on the canonical tag row, so any attribute difference orphans the baseline.
+        tag: {
+          name: b.browserFamily,
+          browserName: b.browserFamily,
+          width: b.width,
+          height: b.height
+        },
+        tiles: [{
+          filepath: b.filepath
+        }]
+      });
+    } else {
+      await client.sendSnapshot(buildId, {
+        name: b.name,
+        widths: [clampDimension(b.width, 1280)],
+        minHeight: clampDimension(b.height, 1024),
+        resources: await imageSnapshotResources(b)
+      });
+    }
+  };
+  let worker = async () => {
+    for (let b = queue.shift(); b; b = queue.shift()) {
+      try {
+        await uploadOne(b);
+        seeded += 1;
+        log.progress(`Uploading baseline snapshots: ${seeded}/${baselines.length}`, true);
+      } catch (err) {
+        log.warn(`Skipped baseline snapshot "${b.name}": ${err.message}`);
+      }
+    }
+  };
+  await Promise.all(Array.from({
+    length: Math.min(SEED_CONCURRENCY, baselines.length)
+  }, worker));
+  return seeded;
+}

package/dist/exec.js

@@ -5,6 +5,8 @@ import stop from './stop.js';
 import ping from './ping.js';
 import replay from './replay.js';
 import { waitForTimeout } from '@percy/client/utils';
+import { yieldTo } from '@percy/cli-command/utils';
+import { findBaselineProvider, maybeSeedBaseline } from './baseline.js';
 export const exec = command('exec', {
   description: 'Start and stop Percy around a supplied command',
   usage: '[options] [--] <command>',
@@ -83,6 +85,28 @@ export const exec = command('exec', {
       } else {
         log.debug('Skipping percy project attribute calculation');
       }
+
+      // Drop-in baseline seeding: when an installed SDK declares a baseline provider and the
+      // Percy project is empty, committed baseline screenshots are uploaded as an auto-approved
+      // build #1 before the head build starts. Never throws. Automate projects get the head-build
+      // source tag only — their captures happen on the remote BrowserStack browser, so committed
+      // local screenshots can never pair with them and the baseline comes from the first run.
+      if (['web', 'app', 'automate'].includes(percy.projectType)) {
+        let provider = await findBaselineProvider({
+          log
+        });
+        if (provider) {
+          // Tag the head build so the API can key drop-in behavior on its source.
+          if (provider.buildSource && !process.env.PERCY_BUILD_SOURCE) {
+            process.env.PERCY_BUILD_SOURCE = provider.buildSource;
+          }
+          // yieldTo keeps the runner tick-responsive — a bare yield would make the up-to-10min
+          // seed wait the one place Ctrl-C can't unwind until the promise settles.
+          yield* yieldTo(maybeSeedBaseline(percy, provider, {
+            log
+          }));
+        }
+      }
       yield* percy.yield.start();
     } catch (error) {
       if (error.name === 'AbortError') throw error;

package/dist/index.js

@@ -2,4 +2,7 @@ export { default, exec } from './exec.js';
 export { start } from './start.js';
 export { stop } from './stop.js';
 export { ping } from './ping.js';
-export { replay } from './replay.js';
+export { replay } from './replay.js';
+// Baseline seeding building blocks, reused by SDK-contributed setup commands
+// (e.g. @percy/playwright's `percy playwright:setup-baseline`).
+export { findBaselineProvider, maybeSeedBaseline, uploadBaselines } from './baseline.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/cli-exec",
-  "version": "1.32.5",
+  "version": "1.32.6-beta.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -9,7 +9,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "latest"
+    "tag": "beta"
   },
   "engines": {
     "node": ">=14"
@@ -34,10 +34,10 @@
     ]
   },
   "dependencies": {
-    "@percy/cli-command": "1.32.5",
-    "@percy/logger": "1.32.5",
+    "@percy/cli-command": "1.32.6-beta.0",
+    "@percy/logger": "1.32.6-beta.0",
     "cross-spawn": "^7.0.3",
     "which": "^2.0.2"
   },
-  "gitHead": "1c83908c5913e3fab1cdd7207db49a2e0c27a3e9"
+  "gitHead": "735e1589b696e9b74f52d9cb0944c6bc0af889b2"
 }