pursor 0.2.0 → 0.3.0

package/src/auth.js

@@ -0,0 +1,92 @@
+// 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; }
+}

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/index.js

@@ -1,90 +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";
-
-
-// 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,
-  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,
+// 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/runway.js

@@ -50,7 +50,7 @@ export async function launch() {
   return await chromium.launch({ headless: true, executablePath: exec, args: BROWSER_ARGS });
 }
 
-export async function newPage(browser, viewport) {
+export async function newPage(browser, viewport, opts = {}) {
   const ctx = await browser.newContext({
     viewport: { width: viewport.width, height: viewport.height },
     deviceScaleFactor: viewport.dpr || 1,
@@ -58,6 +58,9 @@ export async function newPage(browser, viewport) {
     colorScheme: "light",
     hasTouch: !!(viewport.name && viewport.name.startsWith("mobile")),
     isMobile: !!(viewport.name && viewport.name.startsWith("mobile")),
+    storageState: opts.storageState || undefined,
   });
-  return await ctx.newPage();
+  const page = await ctx.newPage();
+  page._pursorContext = ctx;
+  return page;
 }

package/src/shoot.js

@@ -9,6 +9,8 @@ import {
 } from "./overlays.js";
 import { asNum, asBool, nowIso, writeSidecar, requireArg } from "./util.js";
 import { runBeforeShoot, runAfterShoot } from "./plugin.js";
+import { startHarCapture, stopHarCapture, writeHar } from "./har.js";
+import { loadAuthState } from "./auth.js";
 
 export async function runShoot({ url, out, flags = {}, prepare, browser: extBrowser }) {
   requireArg("url", url, "string");
@@ -18,7 +20,9 @@ export async function runShoot({ url, out, flags = {}, prepare, browser: extBrow
   const cleanups = [];
   try {
     return await (async () => {
-      const page = await newPage(browser, viewport);
+      const page = await newPage(browser, viewport, {
+        storageState: flags["auth-state"] ? loadAuthState({ project: flags["auth-project"] || "default", name: flags["auth-state"] }) : undefined,
+      });
       const r = await gotoOrThrow(page, url);
       await settle(page);
 
@@ -41,8 +45,16 @@ export async function runShoot({ url, out, flags = {}, prepare, browser: extBrow
         await page.waitForTimeout(400);
       }
 
+      // Optional HAR capture
+      const harState = flags.har ? await startHarCapture(page) : null;
       await page.screenshot({ path: out, fullPage: asBool(flags.full, false) });
       const meta = { url, out, ts: nowIso(), status: r.status, title: r.title, viewport, flags: { ...flags } };
+      if (harState) {
+        const har = stopHarCapture(page);
+        const harFile = await writeHar(har, String(flags.har));
+        meta.har = harFile;
+        meta.harEntryCount = har?._meta?.entryCount || 0;
+      }
       await runAfterShoot(ctx, meta);
       return meta;
     })().catch(e => ({ url, out, ts: nowIso(), error: e.message, viewport, flags: { ...flags } }));