pursr 0.7.1 → 0.7.2

package/bin/pursr.mjs

@@ -205,6 +205,12 @@ await loadPlugins(pluginPaths);
           let meta = null;
           if (flags["meta-json"]) meta = JSON.parse(readFile(flags["meta-json"], "utf8"));
           else if (flags.url) meta = { url: flags.url };
+          else {
+            const sidecar = png.replace(/\.png$/i, ".json");
+            if (existsSync(sidecar)) {
+              try { meta = JSON.parse(readFile(sidecar, "utf8")); } catch { meta = null; }
+            }
+          }
           const id = flags.id || diffKey({ url: meta?.url || "", viewport: meta?.viewport, flags: meta?.flags || {} });
           const result = saveBaseline({ project, id, step, png, meta });
           console.log(JSON.stringify({ saved: true, ...result }, null, 2));
@@ -318,6 +324,18 @@ await loadPlugins(pluginPaths);
               }
               break;
             }
+            case "check": {
+              // pursr check <url> [--preset <name>] [--update] [--json] [--threshold 0.1] [--out <diff.png>]
+              if (!url) die("check: missing <url>");
+              const flags = parseFlags(argv.slice(4));
+              const update = !!flags.update;
+              const threshold = flags.threshold !== undefined ? Number(flags.threshold) : 0.1;
+              const { runCheck } = await import("../src/check.js");
+              const r = await runCheck({ url, flags, threshold, update, out: flags.out || null });
+              if (flags.json) console.log(JSON.stringify(r, null, 2));
+              else console.log(JSON.stringify(r, null, 2));
+              process.exit(r.exitCode || 0);
+            }
             default: { die(`unknown subcommand: ${cmd}`); }
     }
   } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pursr",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "private": false,
   "description": "pursr — Visual QA, audit, and MCP for the browser. One CLI + one MCP server for screenshots, sweeps, baselines, diffs, axe-core a11y audits, HAR capture, and auth state — with parallel sweep workers, auto-healing selectors, and a plugin system. Zero browser bundled: drives your system Chrome via Playwright.",
   "homepage": "https://github.com/0xheycat/pursr",

package/src/baseline.js

@@ -28,7 +28,8 @@ import { __PURSR_GET } from "./util.js";
 
 function baseDir(project) {
   const root = __PURSR_GET("PURSR_BASELINES_DIR") || join(homedir(), ".pursr", "baselines");
-  const proj = (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
+  // Normalize: strip trailing slashes so "http://x/" and "http://x" map to the same folder.
+  const proj = String(project || "default").replace(/\/+$/, "").replace(/[^a-zA-Z0-9._-]+/g, "_") || "default";
   return join(root, proj);
 }
 

package/src/check.js

@@ -0,0 +1,77 @@
+//  pursr — CI-friendly visual regression check.
+//
+// Renders a URL at a given (url + viewport + flags) and diffs it against the
+// stored baseline (identified by the same diffKey). Exits 0 if equal, 1 if
+// different, 2 if no baseline.
+
+import { resolveViewport } from "./viewport.js";
+import { diffKey, loadBaseline, approveBaseline } from "./baseline.js";
+import { runDiff } from "./diff.js";
+import { makeOut, nowIso } from "./util.js";
+
+export async function runCheck({ url, flags = {}, project = null, threshold = 0.1, update = false, out = null, baselineStep = "default" }) {
+  if (!url) throw new Error("runCheck: missing url");
+  // Strip action-only flags that don't affect rendering. If they were part of the
+  // diffKey, the same URL+preset combo would hash differently depending on which
+  // CLI flags the user passed, which is wrong.
+  const renderFlags = {};
+  for (const [k, v] of Object.entries(flags || {})) {
+    if (k === "update" || k === "threshold" || k === "out" || k === "json" || k === "project") continue;
+    renderFlags[k] = v;
+  }
+  const viewport = resolveViewport(renderFlags);
+  const id = diffKey({ url, viewport, flags: renderFlags });
+  let proj = project;
+  if (!proj) {
+    try { const u = new URL(url); proj = u.origin + (u.pathname === "/" ? "/" : u.pathname.replace(/\/$/, "")); }
+    catch { proj = url; }
+  }
+  const loaded = loadBaseline({ project: proj, id, step: baselineStep });
+  if (!loaded) {
+    return {
+      url, flags, viewport, baselineKey: { project: proj, id, step: baselineStep },
+      status: "no-baseline",
+      exitCode: 2,
+      ts: nowIso(),
+      hint: "No baseline found. Run `pursr shoot " + url + " --save-baseline` first, or `pursr check " + url + " --update` to capture the current render as the new baseline.",
+    };
+  }
+  const diffOut = out || makeOut("check-diff.png");
+  const result = await runDiff(url, loaded.png, diffOut, threshold, flags);
+  if (result.error === "size mismatch") {
+    return {
+      url, flags, viewport, baselineKey: { project: proj, id, step: baselineStep },
+      refPng: loaded.png, currentPath: result.currentPath, out: diffOut,
+      status: "size-mismatch",
+      equal: false,
+      refSize: result.refSize, currentSize: result.currentSize,
+      exitCode: 1,
+      ts: nowIso(),
+      hint: "Reference baseline is " + result.refSize.w + "x" + result.refSize.h + " but current render is " + result.currentSize.w + "x" + result.currentSize.h + ". Re-baseline with the same viewport.",
+    };
+  }
+  if (update || result.numDiff === 0) {
+    const currentPng = result.currentPath;
+    const saved = (update || result.numDiff > 0) ? approveBaseline({ project: proj, id, step: baselineStep, fromPng: currentPng }) : null;
+    return {
+      url, flags, viewport, baselineKey: { project: proj, id, step: baselineStep },
+      refPng: loaded.png, currentPath: currentPng, out: diffOut,
+      refSize: result.refSize, totalPx: result.totalPx, numDiff: result.numDiff, diffPct: result.diffPct, threshold,
+      status: result.numDiff === 0 ? "equal" : "updated",
+      equal: result.numDiff === 0,
+      exitCode: 0,
+      saved: saved ? { ts: saved.ts, sha1: saved.sha1, approvedFrom: saved.approvedFrom } : null,
+      ts: nowIso(),
+    };
+  }
+  return {
+    url, flags, viewport, baselineKey: { project: proj, id, step: baselineStep },
+    refPng: loaded.png, currentPath: result.currentPath, out: diffOut,
+    refSize: result.refSize, totalPx: result.totalPx, numDiff: result.numDiff, diffPct: result.diffPct, threshold,
+    status: "differ",
+    equal: false,
+    exitCode: 1,
+    ts: nowIso(),
+    hint: "Differences detected (" + result.numDiff + " px, " + result.diffPct + "%). Run `pursr check " + url + " --update` to approve the current render as the new baseline.",
+  };
+}

package/src/index.js

@@ -41,6 +41,7 @@ import { startHarCapture, stopHarCapture, writeHar } from "./har.js";
 import { saveAuthState, loadAuthState, listAuthStates, deleteAuthState } from "./auth.js";
 import { startWatch, matchGlob, shouldFire } from "./watch.js";
 import { runSnap, approveSnapsAsBaselines } from "./snap.js";
+import { runCheck } from "./check.js";
 import { renderSweepPdf } from "./report.js";
 import { aiDiffSummary, aiDiffSidecar } from "./ai-diff.js";
 
@@ -71,6 +72,8 @@ export {
   PursrMCPServer, loadMcpConfig, MCP_VERSION,
   // v4: baselines, sweep validation, MCP resources
   saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath,
+  // v0.7.2: CI visual regression check
+  runCheck,
   validateSweepPlan, registerSweepOp,
   listResources, readResource, recordResource,
   // v5: HAR capture, auth state, parallel sweep

package/src/mcp.js

@@ -7,13 +7,14 @@
 // Config via PURSR_MCP_CONFIG env or ~/./mcp-config.json:
 //   { "plugins": ["./my-plugin.js"], "defaultOutDir": "./mcp-output" }
 
-import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { __PURSR_GET } from "./util.js";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { runProbe } from "./probe.js";
 import { runShoot } from "./shoot.js";
 import { runDiff } from "./diff.js";
+import { runCheck } from "./check.js";
 import { runSweep } from "./sweep.js";
 import { runFrames } from "./frames.js";
 import { runShootWithSidecar } from "./shoot.js";
@@ -236,14 +237,28 @@ class PursrMCPServer {
       },
       {
         name: "pursr_diff",
-        description: "Pixel-diff a URL against a reference PNG. Returns diff stats and writes diff overlay image.",
+        description: "Pixel-diff a URL against a reference PNG. Honors the same viewport/camera/animation flags as pursr_shoot. Returns diff stats and writes diff overlay image.",
         inputSchema: {
           type: "object",
           properties: {
-            url:       { type: "string", description: "URL to capture" },
-            ref:       { type: "string", description: "Reference PNG path" },
-            out:       { type: "string", description: "Diff output PNG (auto-gen if omitted)" },
-            threshold: { type: "number", description: "Pixelmatch threshold 0-1 (default 0.1)" },
+            url:           { type: "string", description: "URL to capture" },
+            ref:           { type: "string", description: "Reference PNG path" },
+            out:           { type: "string", description: "Diff output PNG (auto-gen if omitted)" },
+            threshold:     { type: "number", description: "Pixelmatch threshold 0-1 (default 0.1)" },
+            preset:        { type: "string", description: "Viewport preset" },
+            width:         { type: "number", description: "Viewport width" },
+            height:        { type: "number", description: "Viewport height" },
+            dpr:           { type: "number", description: "Device pixel ratio" },
+            full:          { type: "boolean", description: "Full-page screenshot" },
+            cursor:        { type: "string", description: "Cursor: default|pointer|grab|grabbing|crosshair|none" },
+            grid:          { type: "boolean", description: "Overlay grid" },
+            zoom:          { type: "number", description: "Camera zoom" },
+            panX:          { type: "number", description: "Camera pan X (px)" },
+            panY:          { type: "number", description: "Camera pan Y (px)" },
+            "no-animation":{ type: "boolean", description: "Freeze CSS animations for a stable diff" },
+            "wait-frame": { type: "number", description: "Wait for stable canvas frame (ms)" },
+            "no-hud":     { type: "boolean", description: "Hide header/footer/nav elements" },
+            settleMs:      { type: "number", description: "Extra settle time before screenshot (ms, default 1200)" },
           },
           required: ["url", "ref"],
         },
@@ -311,6 +326,29 @@ class PursrMCPServer {
           required: ["url"],
         },
       },
+      {
+        name: "pursr_check",
+        description: "CI visual regression check. Renders a URL and diffs against the stored baseline. Exits 0 if equal, 1 if differs, 2 if no baseline. Use update:true to approve current as new baseline.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            url:       { type: "string", description: "Target URL" },
+            preset:    { type: "string", description: "Viewport preset" },
+            width:     { type: "number", description: "Viewport width" },
+            height:    { type: "number", description: "Viewport height" },
+            dpr:       { type: "number", description: "Device pixel ratio" },
+            full:      { type: "boolean", description: "Full-page screenshot" },
+            zoom:      { type: "number", description: "Camera zoom" },
+            panX:      { type: "number", description: "Camera pan X" },
+            panY:      { type: "number", description: "Camera pan Y" },
+            threshold: { type: "number", description: "Pixelmatch threshold 0-1 (default 0.1)" },
+            update:    { type: "boolean", description: "Approve current render as the new baseline" },
+            out:       { type: "string", description: "Diff output PNG path" },
+            project:   { type: "string", description: "Project key (defaults to URL origin+path)" },
+          },
+          required: ["url"],
+        },
+      },
     ];
   }
 
@@ -325,6 +363,7 @@ class PursrMCPServer {
       case "pursr_probe":        return await this._probe(args);
       case "pursr_audit":        return await this._audit(args);
       case "pursr_dom_snapshot": return await this._domSnapshot(args);
+      case "pursr_check":        return await this._check(args);
       default: throw new McpError(-32602, `Unknown tool: ${name}`);
     }
   }
@@ -370,7 +409,11 @@ class PursrMCPServer {
     const out = args.out || ref.replace(/\.png$/i, "-diff.png");
     if (out) mkdirSync(dirname(out), { recursive: true });
     const threshold = args.threshold ?? 0.1;
-    const result = await runDiff(url, ref, out, threshold);
+    const flags = {};
+    for (const [k, v] of Object.entries(args)) {
+      if (k !== "url" && k !== "ref" && k !== "out" && k !== "threshold") flags[k] = v;
+    }
+    const result = await runDiff(url, ref, out, threshold, flags);
     return [{ type: "text", text: JSON.stringify(result, null, 2) }];
   }
 
@@ -432,6 +475,23 @@ class PursrMCPServer {
     const result = await captureDomSnapshot({ url: args.url, out });
     return [{ type: "text", text: JSON.stringify({ out, ...result }, null, 2) }];
   }
+
+  async _check(args) {
+    if (!args.url) throw new McpError(-32602, "Missing required: url");
+    const flags = {};
+    for (const [k, v] of Object.entries(args)) {
+      if (k !== "url" && k !== "threshold" && k !== "update" && k !== "out" && k !== "project") flags[k] = v;
+    }
+    const result = await runCheck({
+      url: args.url,
+      flags,
+      threshold: args.threshold ?? 0.1,
+      update: !!args.update,
+      out: args.out,
+      project: args.project || null,
+    });
+    return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+  }
 }
 
 export { PursrMCPServer, McpError, loadConfig, MCP_VERSION };