pursr 0.4.0

package/src/har.js

@@ -0,0 +1,159 @@
+// pursor — HAR (HTTP Archive) capture.
+//
+// Hooks page.on("request") / page.on("response") / page.on("requestfailed")
+// on an active page and produces a HAR 1.2 spec blob:
+//   { log: { version: "1.2", creator: {...}, browser: {...}, pages: [...], entries: [...] } }
+//
+// Use in code:
+//   const { startHarCapture, stopHarCapture } = await import("pursor/har");
+//   const har = await startHarCapture(page);
+//   await page.goto(url);
+//   await stopHarCapture(page);  // returns the HAR object
+//
+// Or via CLI/sweep:
+//   pursor shoot <url> --har ./out/req.har.json
+//
+// HAR is useful for:
+//   - killing flakiness from analytics/ads/CDN by mocking responses later
+//   - inspecting what the page actually fetched during a capture
+//   - regression diffing along with visual diffs
+
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { nowIso } from "./util.js";
+
+const SYM = Symbol.for("pursor.har.capture");
+
+function makeEntry(req, resp, startTs, endTs) {
+  const url = req.url();
+  const u = new URL(url);
+  const headersList = (obj) => {
+    if (!obj) return [];
+    try {
+      const out = [];
+      for (const [name, value] of Object.entries(obj)) {
+        if (Array.isArray(value)) {
+          for (const v of value) out.push({ name, value: String(v) });
+        } else {
+          out.push({ name, value: String(value) });
+        }
+      }
+      return out;
+    } catch { return []; }
+  };
+  const queryString = u.search ? u.search.slice(1).split("&").filter(Boolean).map(kv => {
+    const [k, v = ""] = kv.split("=");
+    return { name: decodeURIComponent(k), value: decodeURIComponent(v) };
+  }) : [];
+  const postData = req.postData() ? { mimeType: req.postData() || "application/octet-stream", text: req.postData() } : undefined;
+  const entry = {
+    pageref: req.frame()?.url?.() || "_top",
+    startedDateTime: new Date(startTs).toISOString(),
+    time: Math.max(0, endTs - startTs),
+    request: {
+      method: req.method(),
+      url,
+      httpVersion: "HTTP/1.1",
+      cookies: [],
+      headers: headersList(req.headers()),
+      queryString,
+      headersSize: -1,
+      bodySize: postData?.text?.length || 0,
+      postData,
+    },
+    response: resp ? {
+      status: resp.status(),
+      statusText: resp.statusText() || "",
+      httpVersion: "HTTP/1.1",
+      cookies: [],
+      headers: headersList(resp.headers()),
+      content: { size: -1, mimeType: resp.headers()?.["content-type"] || "" },
+      redirectURL: resp.headers()?.location || "",
+      headersSize: -1,
+      bodySize: -1,
+    } : { status: 0, statusText: "Failed", httpVersion: "HTTP/1.1", cookies: [], headers: [], content: { size: 0, mimeType: "" }, redirectURL: "", headersSize: -1, bodySize: -1 },
+    cache: {},
+    timings: { send: 0, wait: Math.max(0, endTs - startTs), receive: 0 },
+    serverIPAddress: "",
+    connection: "",
+  };
+  return entry;
+}
+
+export async function startHarCapture(page, opts = {}) {
+  if (!page) throw new Error("startHarCapture: page required");
+  if (page[SYM]) return page[SYM]; // idempotent
+  const started = Date.now();
+  const entries = [];
+  const pending = new Map(); // req -> startTs
+  const state = {
+    started,
+    creator: { name: "pursor", version: opts.version || "0.3.0" },
+    browser: { name: "chromium", version: "playwright-core" },
+    pages: [],
+    entries,
+    pending,
+  };
+  const onReq = (req) => {
+    pending.set(req, Date.now());
+  };
+  const onResp = async (resp) => {
+    try {
+      const req = resp.request();
+      const startTs = pending.get(req) || Date.now();
+      pending.delete(req);
+      const endTs = Date.now();
+      entries.push(makeEntry(req, resp, startTs, endTs));
+    } catch {}
+  };
+  const onFailed = (req) => {
+    try {
+      const startTs = pending.get(req) || Date.now();
+      pending.delete(req);
+      entries.push(makeEntry(req, null, startTs, Date.now()));
+    } catch {}
+  };
+  page.on("request", onReq);
+  page.on("response", onResp);
+  page.on("requestfailed", onFailed);
+  state._teardown = () => {
+    try { page.off("request", onReq); } catch {}
+    try { page.off("response", onResp); } catch {}
+    try { page.off("requestfailed", onFailed); } catch {}
+  };
+  page[SYM] = state;
+  return state;
+}
+
+export function stopHarCapture(page) {
+  if (!page || !page[SYM]) return null;
+  const state = page[SYM];
+  try { state._teardown?.(); } catch {}
+  delete page[SYM];
+  return finalizeHar(state);
+}
+
+export function finalizeHar(state) {
+  if (!state) return null;
+  return {
+    log: {
+      version: "1.2",
+      creator: state.creator,
+      browser: state.browser,
+      pages: state.pages,
+      entries: state.entries,
+    },
+    _meta: {
+      started: state.started,
+      finished: Date.now(),
+      entryCount: state.entries.length,
+    },
+  };
+}
+
+export async function writeHar(har, file) {
+  if (!har || !file) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(har, null, 2), "utf8");
+  return file;
+}

package/src/hover.js

@@ -0,0 +1,26 @@
+// Hover capture: navigate, hover a selector, screenshot.
+
+import { launch, newPage } from "./runway.js";
+import { resolveViewport } from "./viewport.js";
+import { gotoOrThrow, settle, CLICK_TIMEOUT_MS } from "./overlays.js";
+import { resolveLocator } from "./selector.js";
+import { asNum, asBool, nowIso, writeSidecar, requireArg } from "./util.js";
+
+export async function runHover({ url, selector, out, flags = {} }) {
+  requireArg("url", url, "string");
+  requireArg("selector", selector, "string");
+  const viewport = resolveViewport(flags);
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, viewport);
+    const r = await gotoOrThrow(page, url); await settle(page);
+    const loc = await resolveLocator(page, selector);
+    await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+    await loc.first().hover({ timeout: CLICK_TIMEOUT_MS });
+    await page.waitForTimeout(asNum(flags["hover-ms"], 250));
+    if (out) await page.screenshot({ path: out, fullPage: asBool(flags.full, false) });
+    const meta = { ...r, url, out, selector, viewport, ts: nowIso() };
+    if (out) await writeSidecar(meta);
+    return meta;
+  } finally { try { await browser.close(); } catch {} }
+}

package/src/index.js

@@ -0,0 +1,95 @@
+// pursor — public library API.
+//
+// This is the entry point for consumers who want to embed pursor
+// inside their own scripts (instead of using the CLI). The CLI in
+// bin/pursor.mjs is a thin wrapper around the same exports.
+//
+// All capture / sweep helpers return a `Result` object: the path to the
+// PNG, a sidecar JSON metadata object, and timing info. They never throw
+// on capture-time errors — those are reported in the result so the
+// caller can decide how to react.
+//
+// The plugin system lives in src/plugin.js — see that file for how to
+// write a custom plugin (viewport, sweep-op, before/after hooks).
+
+import { runShoot } from "./shoot.js";
+import { runSweep } from "./sweep.js";
+import { runEveryViewport } from "./every-viewport.js";
+import { runFrames } from "./frames.js";
+import { runHover } from "./hover.js";
+import { runDiff } from "./diff.js";
+import { runProbe } from "./probe.js";
+import { runShot } from "./shot.js";
+import { runEval } from "./eval.js";
+import { runClick, runType, runWait, runSeq } from "./interact.js";
+import { listViewports, resolveViewport, VIEWPORTS } from "./viewport.js";
+import { applyCamera, waitForStableFrame } from "./overlays.js";
+import { loadPlugins, registerPlugin, listPlugins, getSweepOp, getViewportPreset, listViewportPresets, getFlagHelp } from "./plugin.js";
+import { launch, newPage } from "./runway.js";
+import { parseFlags, asNum, asBool, nowIso, shortHash, escapeHtml, renderSweepHtml, renderEveryViewportHtml, findStepPng, readArg, makeOut } from "./util.js";
+import { resolveLocator, parseTextSelector } from "./selector.js";
+import { captureDomSnapshot, captureDomSnapshotSidecar } from "./dom-snapshot.js";
+import { runAudit } from "./plugin-audit.js";
+import { resolveHealedSelector, healStepAction } from "./selector-heal.js";
+import { writeCiOutput } from "./ci-output.js";
+import { PursorMCPServer, loadConfig as loadMcpConfig, MCP_VERSION } from "./mcp.js";
+import { createRequire } from "node:module";
+import { saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath } from "./baseline.js";
+import { validateSweepPlan, registerSweepOp } from "./sweep-schema.js";
+import { listResources, readResource, recordResource } from "./mcp-resources.js";
+import { startHarCapture, stopHarCapture, writeHar } from "./har.js";
+import { saveAuthState, loadAuthState, listAuthStates, deleteAuthState } from "./auth.js";
+
+
+// Derive VERSION from package.json to prevent drift
+const __require = createRequire(import.meta.url);
+const pkg = __require("../package.json");
+const VERSION = pkg.version;
+
+export {
+  // CLI-style actions
+  runProbe, runShot, runEval, runClick, runType, runWait, runSeq,
+  runShoot, runFrames, runHover, runSweep, runDiff, runEveryViewport,
+  // v3: audit, DOM snapshot, MCP
+  runAudit, captureDomSnapshot, captureDomSnapshotSidecar,
+  // viewport + camera helpers
+  listViewports, resolveViewport, VIEWPORTS,
+  applyCamera, waitForStableFrame,
+  // plugin system
+  loadPlugins, registerPlugin, listPlugins, getSweepOp, getViewportPreset, listViewportPresets, getFlagHelp,
+  // low-level helpers (for plugin authors)
+  launch, newPage,
+  parseFlags, asNum, asBool, nowIso, shortHash, escapeHtml, renderSweepHtml, renderEveryViewportHtml, findStepPng, readArg, makeOut,
+  resolveLocator, parseTextSelector,
+  // v3: selector healing, CI output, MCP server
+  resolveHealedSelector, healStepAction,
+  writeCiOutput,
+  PursorMCPServer, loadMcpConfig, MCP_VERSION,
+  // v4: baselines, sweep validation, MCP resources
+  saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath,
+  validateSweepPlan, registerSweepOp,
+  listResources, readResource, recordResource,
+  // v5: HAR capture, auth state, parallel sweep
+  startHarCapture, stopHarCapture, writeHar,
+  saveAuthState, loadAuthState, listAuthStates, deleteAuthState,
+  VERSION,
+};
+
+export default {
+  runProbe, runShot, runEval, runClick, runType, runWait, runSeq,
+  runShoot, runFrames, runHover, runSweep, runDiff, runEveryViewport,
+  runAudit, captureDomSnapshot, captureDomSnapshotSidecar,
+  listViewports, resolveViewport, VIEWPORTS,
+  applyCamera, waitForStableFrame,
+  loadPlugins, registerPlugin, listPlugins, getSweepOp, getViewportPreset, listViewportPresets, getFlagHelp,
+  launch, newPage,
+  parseFlags, asNum, asBool, nowIso, shortHash, escapeHtml, renderSweepHtml, renderEveryViewportHtml, findStepPng, readArg, makeOut,
+  resolveLocator, parseTextSelector,
+  resolveHealedSelector, healStepAction,
+  writeCiOutput,
+  PursorMCPServer, loadMcpConfig, MCP_VERSION,
+  saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath,
+  validateSweepPlan, registerSweepOp,
+  listResources, readResource, recordResource,
+  VERSION,
+};

package/src/interact.js

@@ -0,0 +1,138 @@
+// click, type, wait, seq — interaction primitives.
+
+import { launch, newPage } from "./runway.js";
+import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { gotoOrThrow, settle, CLICK_TIMEOUT_MS, WAIT_DEFAULT_TIMEOUT_MS } from "./overlays.js";
+import { resolveLocator } from "./selector.js";
+import { requireArg } from "./util.js";
+
+export async function runClick(url, selector, out) {
+  requireArg("url", url, "string");
+  requireArg("selector", selector, "string");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const r = await gotoOrThrow(page, url); await settle(page);
+    const loc = await resolveLocator(page, selector);
+    await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+    await loc.first().click({ timeout: CLICK_TIMEOUT_MS });
+    await settle(page);
+    if (out) await page.screenshot({ path: out, fullPage: false });
+    return { ...r, url, out, selector, clicked: true };
+  } finally { try { await browser.close(); } catch {} }
+}
+
+export async function runType(url, selector, text, out) {
+  requireArg("url", url, "string");
+  requireArg("selector", selector, "string");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const r = await gotoOrThrow(page, url); await settle(page);
+    const loc = await resolveLocator(page, selector);
+    await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+    await loc.first().click({ timeout: CLICK_TIMEOUT_MS });
+    await page.keyboard.type(String(text ?? ""), { delay: 10 });
+    await settle(page);
+    if (out) await page.screenshot({ path: out, fullPage: false });
+    return { ...r, url, out, selector, text, typed: true };
+  } finally { try { await browser.close(); } catch {} }
+}
+
+export async function runWait(url, selector, timeoutMs) {
+  requireArg("url", url, "string");
+  requireArg("selector", selector, "string");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const r = await gotoOrThrow(page, url);
+    const loc = await resolveLocator(page, selector);
+    const t = timeoutMs || WAIT_DEFAULT_TIMEOUT_MS;
+    try {
+      await loc.first().waitFor({ state: "visible", timeout: t });
+      return { ...r, url, selector, found: true, timeoutMs: t };
+    } catch {
+      return { ...r, url, selector, found: false, timeoutMs: t };
+    }
+  } finally { try { await browser.close(); } catch {} }
+}
+
+export async function runSeq(url, actionsJson, out) {
+  requireArg("url", url, "string");
+  let actions;
+  try { actions = JSON.parse(actionsJson); }
+  catch (e) { throw new Error(`invalid actions JSON: ${e.message}`, { cause: e }); }
+  if (!Array.isArray(actions)) throw new Error("actions must be a JSON array");
+  if (!actions.length) throw new Error("actions array is empty");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const r = await gotoOrThrow(page, url); await settle(page);
+    const trace = [];
+    let failed = false;
+    for (let i = 0; i < actions.length; i++) {
+      const a = actions[i] || {};
+      const step = { i, op: a.op };
+      try {
+        switch (a.op) {
+          case "click": {
+            const loc = await resolveLocator(page, a.selector);
+            await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+            await loc.first().click({ timeout: CLICK_TIMEOUT_MS });
+            step.selector = a.selector; break;
+          }
+          case "type": {
+            const loc = await resolveLocator(page, a.selector);
+            await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+            await loc.first().click({ timeout: CLICK_TIMEOUT_MS });
+            await page.keyboard.type(String(a.text ?? ""), { delay: 10 });
+            step.selector = a.selector; step.text = a.text; break;
+          }
+          case "wait": {
+            const t = a.timeoutMs ? Number(a.timeoutMs) : WAIT_DEFAULT_TIMEOUT_MS;
+            const loc = await resolveLocator(page, a.selector);
+            await loc.first().waitFor({ state: "visible", timeout: t });
+            step.selector = a.selector; step.timeoutMs = t; break;
+          }
+          case "eval": { step.result = await page.evaluate(String(a.js ?? "")); break; }
+          case "shot": {
+            await page.screenshot({ path: a.out, fullPage: !!a.fullPage });
+            step.out = a.out; step.fullPage = !!a.fullPage; break;
+          }
+          case "scroll": {
+            const vp = page.viewportSize();
+            await page.mouse.move((vp?.width || 640) / 2, (vp?.height || 400) / 2);
+            await page.mouse.wheel(a.deltaX || 0, a.deltaY || 0);
+            step.deltaX = a.deltaX; step.deltaY = a.deltaY; break;
+          }
+          case "navigate": { await gotoOrThrow(page, a.url); step.url = a.url; break; }
+          case "press": {
+            // a.key can be a single key ("Escape") or comma-separated ("Tab,Enter")
+            const raw = String(a.key ?? "").trim();
+            if (!raw) throw new Error("press: missing key");
+            const keys = raw.split(",").map(k => k.trim()).filter(Boolean);
+            for (const k of keys) await page.keyboard.press(k);
+            step.key = raw; step.count = keys.length; break;
+          }
+          case "sleep": { await page.waitForTimeout(Number(a.ms ?? 1000)); step.ms = a.ms; break; }
+          case "hover": {
+            const loc = await resolveLocator(page, a.selector);
+            await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+            await loc.first().hover({ timeout: CLICK_TIMEOUT_MS });
+            step.selector = a.selector; break;
+          }
+          default: throw new Error(`unknown op: ${a.op}`);
+        }
+        if (a.settleMs !== undefined) await page.waitForTimeout(Number(a.settleMs));
+        else await settle(page);
+        step.ok = true;
+      } catch (e) {
+        step.ok = false; step.error = e.message; failed = true;
+      }
+      trace.push(step);
+      if (failed) break;
+    }
+    if (out) await page.screenshot({ path: out, fullPage: false });
+    return { ...r, url, out, steps: trace, failed };
+  } finally { try { await browser.close(); } catch {} }
+}

package/src/mcp-resources.js

@@ -0,0 +1,111 @@
+// pursor — MCP resources adapter.
+//
+// Exposes run results as MCP resources so hosts (Claude Code, Cursor, etc.)
+// can browse, preview, and re-read captures without re-running captures.
+//
+// Resource shape (per MCP spec):
+//   uri:        pursor://<kind>/<id>
+//   name:       <human label>
+//   description: <what it is>
+//   mimeType:   image/png | application/json | text/html
+//
+// We track "recent" sweep outputs in-memory + persist an index at
+// $PURSOR_MCP_STATE/mcp-index.json so resources survive restarts.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { homedir } from "node:os";
+import { nowIso } from "./util.js";
+
+function stateDir() {
+  const root = process.env.PURSOR_MCP_STATE || join(homedir(), ".pursor", "mcp");
+  mkdirSync(root, { recursive: true });
+  return root;
+}
+
+function indexPath() { return join(stateDir(), "mcp-index.json"); }
+
+function loadIndex() {
+  const p = indexPath();
+  if (!existsSync(p)) return { resources: [] };
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return { resources: [] }; }
+}
+
+function saveIndex(idx) {
+  writeFileSync(indexPath(), JSON.stringify(idx, null, 2), "utf8");
+}
+
+export function recordResource({ kind, id, name, description, uri, mimeType, file, meta }) {
+  const idx = loadIndex();
+  // De-dup by uri
+  idx.resources = idx.resources.filter(r => r.uri !== uri);
+  idx.resources.unshift({
+    kind, id, name, description, uri, mimeType, file, meta: meta || null, ts: nowIso(),
+  });
+  // Cap index size
+  if (idx.resources.length > 200) idx.resources = idx.resources.slice(0, 200);
+  saveIndex(idx);
+  return idx.resources[0];
+}
+
+export function listResources() {
+  // Combine persisted index + any in-memory scan of recent sweep dirs
+  const idx = loadIndex();
+  // Also include sidecars sitting next to a sweep.json under cwd
+  try {
+    const cwd = process.cwd();
+    for (const f of readdirSync(cwd)) {
+      if (f === "sweep.json") {
+        const sweepPath = join(cwd, f);
+        try {
+          const s = JSON.parse(readFileSync(sweepPath, "utf8"));
+          const dirUri = `pursor://sweep/${encodeURIComponent(s.name || basename(cwd))}`;
+          if (!idx.resources.some(r => r.uri === dirUri)) {
+            idx.resources.push({
+              kind: "sweep", id: s.name || basename(cwd),
+              name: `sweep: ${s.name || basename(cwd)}`,
+              description: `Sweep summary: ${(s.steps || []).length} steps`,
+              uri: dirUri, mimeType: "application/json",
+              file: sweepPath, meta: { steps: (s.steps || []).length, ts: s.ts }, ts: s.ts || nowIso(),
+            });
+          }
+        } catch {}
+      }
+    }
+  } catch {}
+  return idx.resources;
+}
+
+export function readResource(uri) {
+  if (typeof uri !== "string") return null;
+  if (!uri.startsWith("pursor://")) return null;
+  // Parse kind/id
+  const rest = uri.slice("pursor://".length);
+  const [kind, ...restParts] = rest.split("/");
+  const id = restParts.join("/");
+  const idx = loadIndex();
+  const r = idx.resources.find(x => x.uri === uri);
+  if (r) {
+    return readResourceFile(r);
+  }
+  // Resolve by kind/id from filesystem fallback
+  if (kind === "sweep") {
+    const file = join(process.cwd(), decodeURIComponent(id), "sweep.json");
+    if (existsSync(file)) {
+      return { uri, mimeType: "application/json", text: readFileSync(file, "utf8") };
+    }
+  }
+  return null;
+}
+
+function readResourceFile(r) {
+  if (!r.file || !existsSync(r.file)) return { uri: r.uri, mimeType: r.mimeType, error: "file not found" };
+  const data = readFileSync(r.file);
+  if (r.mimeType && r.mimeType.startsWith("image/")) {
+    return { uri: r.uri, mimeType: r.mimeType, blob: data.toString("base64") };
+  }
+  if (r.mimeType === "application/json" || r.mimeType === "text/html") {
+    return { uri: r.uri, mimeType: r.mimeType, text: data.toString("utf8") };
+  }
+  return { uri: r.uri, mimeType: r.mimeType || "application/octet-stream", blob: data.toString("base64") };
+}