pursr 0.6.0 → 0.7.1

package/plugins/plugin-audit.js

@@ -1,57 +1,57 @@
-// Built-in plugin: axe-core accessibility audit.
-//
-// Adds:
-//   viewport  "audit-canvas"     — 1280x800 @1x ideal for audit screenshots
-//   sweepOp   "audit"            — run axe-core WCAG audit in a sweep plan
-//   sweepOp   "every-viewport"   — capture every viewport preset
-//
-// The audit sweep-op stores results to ctx.out/audit.json plus a
-// highlighted screenshot. This is a thin wrapper around src/plugin-audit.js
-// that exposes the same functionality through the plugin system.
-
-import { runAudit } from "../src/plugin-audit.js";
-import { launch, newPage } from "../src/runway.js";
-import { listViewports, resolveViewport } from "../src/viewport.js";
-import { runShootWithSidecar } from "../src/shoot.js";
-import { join } from "node:path";
-import { writeFileSync } from "node:fs";
-
-export default {
-  name: "audit",
-
-  viewport: {
-    "audit-canvas": { width: 1280, height: 800, dpr: 1, label: "Audit canvas 1280x800" },
-  },
-
-  sweepOp: {
-    // Run axe-core accessibility audit
-    "audit": async (ctx, opts) => {
-      const url = opts.url || ctx.url;
-      if (!url) throw new Error("audit: missing url");
-      const tags = opts.tags ? opts.tags.split(",").map(t => t.trim()) : undefined;
-      const outDir = opts.outDir || ctx.out?.replace(/\.png$/i, "-audit") || join(process.cwd(), `audit-${Date.now()}`);
-      const result = await runAudit({ url, tags, outDir, screenshot: opts.screenshot !== false });
-      return { url, mode: "audit", outDir, violations: result.violationSummary?.total || 0, summary: result.violationSummary };
-    },
-
-    // Capture one shot per viewport preset
-    "every-viewport": async (ctx, opts) => {
-      const url = opts.base || ctx.url;
-      if (!url) throw new Error("every-viewport: missing base url");
-      const wanted = opts.viewports?.length ? opts.viewports : listViewports().map(v => v.name);
-      const dir = ctx.out.replace(/\.png$/i, "-every-viewport");
-      const captures = [];
-      for (const name of wanted) {
-        const out = join(dir, `${name}.png`);
-        try {
-          const meta = await runShootWithSidecar({ url, out, flags: { preset: name } });
-          captures.push({ name, out, ok: true, meta });
-        } catch (e) {
-          captures.push({ name, out, ok: false, error: e.message });
-        }
-      }
-      writeFileSync(join(dir, "every-viewport.json"), JSON.stringify({ url, captures, ts: new Date().toISOString() }, null, 2));
-      return { url, mode: "every-viewport", outDir: dir, captures };
-    },
-  },
-};
+// Built-in plugin: axe-core accessibility audit.
+//
+// Adds:
+//   viewport  "audit-canvas"     — 1280x800 @1x ideal for audit screenshots
+//   sweepOp   "audit"            — run axe-core WCAG audit in a sweep plan
+//   sweepOp   "every-viewport"   — capture every viewport preset
+//
+// The audit sweep-op stores results to ctx.out/audit.json plus a
+// highlighted screenshot. This is a thin wrapper around src/plugin-audit.js
+// that exposes the same functionality through the plugin system.
+
+import { runAudit } from "../src/plugin-audit.js";
+import { launch, newPage } from "../src/runway.js";
+import { listViewports, resolveViewport } from "../src/viewport.js";
+import { runShootWithSidecar } from "../src/shoot.js";
+import { join } from "node:path";
+import { writeFileSync } from "node:fs";
+
+export default {
+  name: "audit",
+
+  viewport: {
+    "audit-canvas": { width: 1280, height: 800, dpr: 1, label: "Audit canvas 1280x800" },
+  },
+
+  sweepOp: {
+    // Run axe-core accessibility audit
+    "audit": async (ctx, opts) => {
+      const url = opts.url || ctx.url;
+      if (!url) throw new Error("audit: missing url");
+      const tags = opts.tags ? opts.tags.split(",").map(t => t.trim()) : undefined;
+      const outDir = opts.outDir || ctx.out?.replace(/\.png$/i, "-audit") || join(process.cwd(), `audit-${Date.now()}`);
+      const result = await runAudit({ url, tags, outDir, screenshot: opts.screenshot !== false });
+      return { url, mode: "audit", outDir, violations: result.violationSummary?.total || 0, summary: result.violationSummary };
+    },
+
+    // Capture one shot per viewport preset
+    "every-viewport": async (ctx, opts) => {
+      const url = opts.base || ctx.url;
+      if (!url) throw new Error("every-viewport: missing base url");
+      const wanted = opts.viewports?.length ? opts.viewports : listViewports().map(v => v.name);
+      const dir = ctx.out.replace(/\.png$/i, "-every-viewport");
+      const captures = [];
+      for (const name of wanted) {
+        const out = join(dir, `${name}.png`);
+        try {
+          const meta = await runShootWithSidecar({ url, out, flags: { preset: name } });
+          captures.push({ name, out, ok: true, meta });
+        } catch (e) {
+          captures.push({ name, out, ok: false, error: e.message });
+        }
+      }
+      writeFileSync(join(dir, "every-viewport.json"), JSON.stringify({ url, captures, ts: new Date().toISOString() }, null, 2));
+      return { url, mode: "every-viewport", outDir: dir, captures };
+    },
+  },
+};

package/plugins/plugin-demo.js

@@ -1,63 +1,63 @@
-// Built-in demo plugin — shows every plugin API surface.
-//
-// Serves as both a reference implementation AND a useful tool:
-//   - adds a `demo-canvas` viewport alias
-//   - adds a `nav` sweep-op that clicks each navbar link in turn
-//     and captures a screenshot per page
-//   - augments sidecar with `demo: { mode }` when `--demo-mode` flag is set
-//
-// Copy this file as a starting point for your own plugin.
-
-import { newPage } from "../src/runway.js";
-import { resolveViewport } from "../src/viewport.js";
-import { gotoOrThrow, settle } from "../src/overlays.js";
-import { resolveLocator } from "../src/selector.js";
-
-export default {
-  name: "demo",
-
-  viewport: {
-    "demo-canvas": { width: 1280, height: 800, dpr: 1, label: "Demo canvas 1280x800" },
-  },
-
-  flagHelp: {
-    "demo-mode": "logical mode label recorded in sidecar (e.g. dark / light / settings).",
-  },
-
-  sweepOp: {
-    "nav": async (ctx, opts) => {
-      // opts: { buttons: string[], settleMs?: number }
-      const browser = ctx.browser;
-      const page = ctx.page || await newPage(browser, resolveViewport({}));
-      const url = ctx.url;
-      if (!url) throw new Error("nav: missing url (provide plan.base)");
-      const r = await gotoOrThrow(page, url); await settle(page);
-      const buttons = opts.buttons || ["Home", "About", "Services", "Portfolio", "Contact"];
-      const frames = [];
-      for (const label of buttons) {
-        try {
-          const loc = await resolveLocator(page, `text=${label}`);
-          await loc.first().waitFor({ state: "visible", timeout: 5000 });
-          await loc.first().click({ timeout: 5000 });
-          await page.waitForTimeout(opts.settleMs || 600);
-          const f = ctx.out.replace(/\.png$/i, `-${label.toLowerCase()}.png`);
-          await page.screenshot({ path: f, fullPage: false });
-          frames.push({ button: label, out: f });
-        } catch (e) {
-          frames.push({ button: label, error: e.message });
-        }
-      }
-      return { ...r, url, mode: "nav-sweep", frames };
-    },
-  },
-
-  beforeShoot: async (ctx) => {
-    if (ctx.flags["demo-mode"]) {
-      ctx._demoMode = ctx.flags["demo-mode"];
-    }
-  },
-
-  afterShoot: async (ctx, meta) => {
-    if (ctx._demoMode) meta.demo = { mode: ctx._demoMode };
-  },
-};
+// Built-in demo plugin — shows every plugin API surface.
+//
+// Serves as both a reference implementation AND a useful tool:
+//   pursr - adds a `demo-canvas` viewport alias
+//   pursr - adds a `nav` sweep-op that clicks each navbar link in turn
+//     and captures a screenshot per page
+//   pursr - augments sidecar with `demo: { mode }` when `--demo-mode` flag is set
+//
+// Copy this file as a starting point for your own plugin.
+
+import { newPage } from "../src/runway.js";
+import { resolveViewport } from "../src/viewport.js";
+import { gotoOrThrow, settle } from "../src/overlays.js";
+import { resolveLocator } from "../src/selector.js";
+
+export default {
+  name: "demo",
+
+  viewport: {
+    "demo-canvas": { width: 1280, height: 800, dpr: 1, label: "Demo canvas 1280x800" },
+  },
+
+  flagHelp: {
+    "demo-mode": "logical mode label recorded in sidecar (e.g. dark / light / settings).",
+  },
+
+  sweepOp: {
+    "nav": async (ctx, opts) => {
+      // opts: { buttons: string[], settleMs?: number }
+      const browser = ctx.browser;
+      const page = ctx.page || await newPage(browser, resolveViewport({}));
+      const url = ctx.url;
+      if (!url) throw new Error("nav: missing url (provide plan.base)");
+      const r = await gotoOrThrow(page, url); await settle(page);
+      const buttons = opts.buttons || ["Home", "About", "Services", "Portfolio", "Contact"];
+      const frames = [];
+      for (const label of buttons) {
+        try {
+          const loc = await resolveLocator(page, `text=${label}`);
+          await loc.first().waitFor({ state: "visible", timeout: 5000 });
+          await loc.first().click({ timeout: 5000 });
+          await page.waitForTimeout(opts.settleMs || 600);
+          const f = ctx.out.replace(/\.png$/i, `-${label.toLowerCase()}.png`);
+          await page.screenshot({ path: f, fullPage: false });
+          frames.push({ button: label, out: f });
+        } catch (e) {
+          frames.push({ button: label, error: e.message });
+        }
+      }
+      return { ...r, url, mode: "nav-sweep", frames };
+    },
+  },
+
+  beforeShoot: async (ctx) => {
+    if (ctx.flags["demo-mode"]) {
+      ctx._demoMode = ctx.flags["demo-mode"];
+    }
+  },
+
+  afterShoot: async (ctx, meta) => {
+    if (ctx._demoMode) meta.demo = { mode: ctx._demoMode };
+  },
+};

package/src/ai-diff.js

@@ -1,4 +1,4 @@
-// pursor - AI diff summary.
+//  pursr - AI diff summary.
 //
 // Sends two images (reference + current) to a vision-capable LLM and asks
 // it to describe the visual differences in plain language. This gives you
@@ -16,12 +16,13 @@
 //   import { aiDiffSummary } from "pursr/ai-diff";
 //   const summary = await aiDiffSummary({ refPath, curPath, url, model });
 
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
+import { __PURSR_GET } from "./util.js";
 
 // Read env at call time so tests can mutate process.env between calls.
-function _defaultBase() { return process.env.PURSOR_AI_BASE_URL || process.env.ANTHROPIC_BASE_URL || "https://api.openai.com/v1"; }
-function _defaultKey()  { return process.env.PURSOR_AI_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN || process.env.OPENAI_API_KEY; }
-function _defaultModel(){ return process.env.PURSOR_AI_MODEL || process.env.ANTHROPIC_DEFAULT_SONNET_MODEL || "gpt-4o"; }
+function _defaultBase() { return __PURSR_GET("PURSR_AI_BASE_URL") || process.env.ANTHROPIC_BASE_URL || "https://api.openai.com/v1"; }
+function _defaultKey()  { return __PURSR_GET("PURSR_AI_API_KEY") || process.env.ANTHROPIC_AUTH_TOKEN || process.env.OPENAI_API_KEY; }
+function _defaultModel(){ return __PURSR_GET("PURSR_AI_MODEL") || process.env.ANTHROPIC_DEFAULT_SONNET_MODEL || "gpt-4o"; }
 
 const SYSTEM_PROMPT = `You are a visual regression analyst. Given two screenshots of the same web page (reference vs current), produce a concise, structured report of the visual differences.
 
@@ -57,7 +58,7 @@ export async function aiDiffSummary(opts) {
   const apiKey = opts.apiKey || _defaultKey();
   const model = opts.model || _defaultModel();
   if (!apiKey) {
-    throw new Error("aiDiffSummary: no API key. Set PURSOR_AI_API_KEY, ANTHROPIC_AUTH_TOKEN, or OPENAI_API_KEY.");
+    throw new Error("aiDiffSummary: no API key. Set PURSR_$1, ANTHROPIC_AUTH_TOKEN, or OPENAI_API_KEY.");
   }
 
   const refB64 = readFileSync(opts.refPath).toString("base64");

package/src/auth.js

@@ -1,92 +1,93 @@
-// pursor — auth state (browser storage state) management.
-//
-// Playwright's `storageState` is the canonical way to persist
-// cookies + localStorage between browser sessions. pursor wraps it
-// in a small CLI/library API so users can:
-//   1. login once interactively and save the state
-//   2. reuse the saved state in any subsequent capture (CI included)
-//
-// Storage layout:
-//   ~/.pursor/auth/<project>/<name>.json
-//
-// Override with PURSOR_AUTH_DIR.
-//
-// Public API:
-//   saveAuthState({ project, name, state })    -> manifest + state file
-//   loadAuthState({ project, name })           -> state object (Playwright shape)
-//   listAuthStates(project)                    -> [{ name, ts, ... }]
-//   deleteAuthState({ project, name })         -> bool
-//
-// CLI:
-//   pursor auth save <project> <name> --from <state.json>
-//   pursor auth load <project> <name> --out <state.json>
-//   pursor auth list [project]
-//   pursor auth delete <project> <name>
-
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-import { nowIso } from "./util.js";
-
-function authRoot() {
-  return process.env.PURSOR_AUTH_DIR || join(homedir(), ".pursor", "auth");
-}
-
-function authPath(project, name) {
-  const root = authRoot();
-  const proj = (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
-  const nm = String(name || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
-  return join(root, proj, `${nm}.json`);
-}
-
-export function saveAuthState({ project, name, state }) {
-  if (!state) throw new Error("saveAuthState: missing state object");
-  // state shape from Playwright: { cookies, origins }
-  if (!Array.isArray(state.cookies)) state.cookies = [];
-  if (!Array.isArray(state.origins)) state.origins = [];
-  const file = authPath(project, name);
-  mkdirSync(join(file, ".."), { recursive: true });
-  const blob = {
-    _meta: { project: project || "default", name, ts: nowIso() },
-    cookies: state.cookies,
-    origins: state.origins,
-  };
-  writeFileSync(file, JSON.stringify(blob, null, 2), "utf8");
-  return { file, ...blob._meta };
-}
-
-export function loadAuthState({ project, name }) {
-  const file = authPath(project, name);
-  if (!existsSync(file)) return null;
-  try {
-    const blob = JSON.parse(readFileSync(file, "utf8"));
-    return { cookies: blob.cookies || [], origins: blob.origins || [] };
-  } catch {
-    return null;
-  }
-}
-
-export function listAuthStates(project) {
-  const root = join(authRoot(), (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_"));
-  if (!existsSync(root)) return [];
-  const out = [];
-  for (const f of readdirSync(root)) {
-    if (!f.endsWith(".json")) continue;
-    try {
-      const blob = JSON.parse(readFileSync(join(root, f), "utf8"));
-      out.push({
-        name: blob?._meta?.name || f.replace(/\.json$/, ""),
-        ts: blob?._meta?.ts || null,
-        cookies: (blob.cookies || []).length,
-        origins: (blob.origins || []).length,
-      });
-    } catch {}
-  }
-  return out.sort((a, b) => (b.ts || "").localeCompare(a.ts || ""));
-}
-
-export function deleteAuthState({ project, name }) {
-  const file = authPath(project, name);
-  if (!existsSync(file)) return false;
-  try { rmSync(file, { force: true }); return true; } catch { return false; }
+//  pursr — auth state (browser storage state) management.
+//
+// Playwright's `storageState` is the canonical way to persist
+// cookies + localStorage between browser sessions. pursr wraps it
+// in a small CLI/library API so users can:
+//   1. login once interactively and save the state
+//   2. reuse the saved state in any subsequent capture (CI included)
+//
+// Storage layout:
+//   ~/.pursr/auth/<project>/<name>.json
+//
+// Override with PURSR_$1.
+//
+// Public API:
+//   saveAuthState({ project, name, state })    -> manifest + state file
+//   loadAuthState({ project, name })           -> state object (Playwright shape)
+//   listAuthStates(project)                    -> [{ name, ts, ... }]
+//   deleteAuthState({ project, name })         -> bool
+//
+// CLI:
+//    auth save <project> <name> --from <state.json>
+//    auth load <project> <name> --out <state.json>
+//    auth list [project]
+//    auth delete <project> <name>
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { nowIso } from "./util.js";
+import { __PURSR_GET } from "./util.js";
+
+function authRoot() {
+  return __PURSR_GET("PURSR_AUTH_DIR") || join(homedir(), ".pursr", "auth");
+}
+
+function authPath(project, name) {
+  const root = authRoot();
+  const proj = (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
+  const nm = String(name || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
+  return join(root, proj, `${nm}.json`);
+}
+
+export function saveAuthState({ project, name, state }) {
+  if (!state) throw new Error("saveAuthState: missing state object");
+  // state shape from Playwright: { cookies, origins }
+  if (!Array.isArray(state.cookies)) state.cookies = [];
+  if (!Array.isArray(state.origins)) state.origins = [];
+  const file = authPath(project, name);
+  mkdirSync(join(file, ".."), { recursive: true });
+  const blob = {
+    _meta: { project: project || "default", name, ts: nowIso() },
+    cookies: state.cookies,
+    origins: state.origins,
+  };
+  writeFileSync(file, JSON.stringify(blob, null, 2), "utf8");
+  return { file, ...blob._meta };
+}
+
+export function loadAuthState({ project, name }) {
+  const file = authPath(project, name);
+  if (!existsSync(file)) return null;
+  try {
+    const blob = JSON.parse(readFileSync(file, "utf8"));
+    return { cookies: blob.cookies || [], origins: blob.origins || [] };
+  } catch {
+    return null;
+  }
+}
+
+export function listAuthStates(project) {
+  const root = join(authRoot(), (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_"));
+  if (!existsSync(root)) return [];
+  const out = [];
+  for (const f of readdirSync(root)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const blob = JSON.parse(readFileSync(join(root, f), "utf8"));
+      out.push({
+        name: blob?._meta?.name || f.replace(/\.json$/, ""),
+        ts: blob?._meta?.ts || null,
+        cookies: (blob.cookies || []).length,
+        origins: (blob.origins || []).length,
+      });
+    } catch {}
+  }
+  return out.sort((a, b) => (b.ts || "").localeCompare(a.ts || ""));
+}
+
+export function deleteAuthState({ project, name }) {
+  const file = authPath(project, name);
+  if (!existsSync(file)) return false;
+  try { rmSync(file, { force: true }); return true; } catch { return false; }
 }