pursr 0.4.0

package/bin/pursr.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+// pursor CLI. Thin wrapper around src/* that mirrors the npm bin.
+
+import { VERSION } from "../src/index.js";
+import { runClick, runType, runWait, runSeq } from "../src/interact.js";
+import { runEval } from "../src/eval.js";
+import { runProbe } from "../src/probe.js";
+import { runShot } from "../src/shot.js";
+import { runShootWithSidecar } from "../src/shoot.js";
+import { runHover } from "../src/hover.js";
+import { runFrames } from "../src/frames.js";
+import { runDiff } from "../src/diff.js";
+import { runSweep } from "../src/sweep.js";
+import { runEveryViewport } from "../src/every-viewport.js";
+import { runAudit } from "../src/plugin-audit.js";
+import { captureDomSnapshot } from "../src/dom-snapshot.js";
+import { listViewports } from "../src/viewport.js";
+import { parseFlags, asNum, readArg, makeOut, pickOutPath } from "../src/util.js";
+import { writeFileSync } from "node:fs";
+import { readFileSync as _readFileSync } from "node:fs";
+const readFile = _readFileSync;
+import { loadPlugins, listPlugins, getFlagHelp } from "../src/plugin.js";
+
+const USAGE = `usage:
+  v1: pursor {probe|shot|full|eval|click|type|wait|diff|seq} <url> [...]
+  v2: pursor {viewports|shoot|layer|frames|hover|sweep} <...>
+  flags: --preset <name> --width N --height N --dpr N
+         --zoom 1.5 --panX 200 --panY -100
+         --cursor pointer|grab|grabbing|crosshair|none
+         --layer entity|terrain|hud|ui
+         --grid --grid-tile 64 --grid-color rgba(255,0,255,0.35)
+         --no-animation --wait-frame 600 --full
+  @file prefix reads argv contents from file (UTF-8, newline trimmed).
+  plugins: pursor automatically loads built-in plugins from plugins/.
+  You can also pass --plugin <path> to load custom plugins (repeatable).`;
+
+function die(msg, code = 2) {
+  console.error(JSON.stringify({ error: msg, usage: USAGE }, null, 2));
+  process.exit(code);
+}
+
+const argv = process.argv;
+const [, , cmd, a, b, c, d] = argv;
+const url = process.env.PURSOR_URL || a;
+
+// Plugin loading: scan for --plugin <path> and built-in plugins/
+const pluginPaths = [];
+for (let i = 0; i < argv.length; i++) if (argv[i] === "--plugin" && i + 1 < argv.length) pluginPaths.push(argv[++i]);
+await loadPlugins(pluginPaths);
+
+(async () => {
+  try {
+    switch (cmd) {
+      case undefined: case "help": case "--help": case "-h": { console.log(JSON.stringify({ usage: USAGE }, null, 2)); break; }
+      case "version": case "--version": case "-v": {
+        console.log(JSON.stringify({ name: "pursor", version: VERSION, plugins: listPlugins() }, null, 2));
+        break;
+      }
+      case "probe": { if (!url) die("missing url"); const r = await runProbe(url); console.log(JSON.stringify(r, null, 2)); break; }
+      case "shot": { if (!url) die("missing url"); const out = b || makeOut("shot.png"); const r = await runShot(url, out, { fullPage: false }); console.log(JSON.stringify(r, null, 2)); break; }
+      case "full": { if (!url) die("missing url"); const out = b || makeOut("full.png"); const r = await runShot(url, out, { fullPage: true }); console.log(JSON.stringify(r, null, 2)); break; }
+      case "eval": { if (!url) die("missing url"); const js = readArg(b); if (!js) die("eval: missing <js> (or @file)"); const out = c || makeOut("eval.png"); const r = await runEval(url, js, out); console.log(JSON.stringify(r, null, 2)); break; }
+      case "click": { if (!url) die("missing url"); const sel = b; if (!sel) die("click: missing <selector>"); const out = c || makeOut(`click-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runClick(url, sel, out); console.log(JSON.stringify(r, null, 2)); break; }
+      case "type": { if (!url) die("missing url"); const sel = b; const text = readArg(c); if (!sel || text === undefined) die("type: missing <selector> or <text> (text can be @file)"); const out = d || makeOut(`type-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runType(url, sel, text, out); console.log(JSON.stringify(r, null, 2)); break; }
+      case "wait": { if (!url) die("missing url"); const sel = b; if (!sel) die("wait: missing <selector>"); const t = c !== undefined ? asNum(c, 30000) : 30000; const r = await runWait(url, sel, t); console.log(JSON.stringify(r, null, 2)); break; }
+      case "diff": { if (!url) die("missing url"); const ref = b; if (!ref) die("diff: missing <ref.png>"); const out = c || makeOut("diff.png"); const threshold = d !== undefined ? Number(d) : 0.1; const r = await runDiff(url, ref, out, threshold); console.log(JSON.stringify(r, null, 2)); break; }
+      case "seq": { if (!url) die("missing url"); const actions = readArg(b); if (!actions) die("seq: missing <actions.json> (or @file)"); const out = c || makeOut("seq.png"); const r = await runSeq(url, actions, out); console.log(JSON.stringify(r, null, 2)); break; }
+      case "viewports": { console.log(JSON.stringify(listViewports(), null, 2)); break; }
+      case "shoot": {
+        if (!url) die("missing url");
+        const out = (b && !b.startsWith("--")) ? b : pickOutPath(argv.slice(5)) || makeOut("shoot.png");
+        const r = await runShootWithSidecar({ url, out, flags: parseFlags(argv.slice(5)) });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "layer": {
+        if (!url) die("missing url");
+        const layerName = b; if (!layerName) die("layer: missing <name>");
+        const out = (c && !c.startsWith("--")) ? c : pickOutPath(argv.slice(6)) || makeOut(`layer-${layerName}.png`);
+        const flags = parseFlags(argv.slice(7)); flags.layer = layerName;
+        const r = await runShootWithSidecar({ url, out, flags });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "frames": {
+        if (!url) die("missing url");
+        const count = asNum(b, 8);
+        const stepMs = asNum(c, 250);
+        const outDir = (d && !d.startsWith("--")) ? d : makeOut(`frames-${count}x${stepMs}ms`);
+        const r = await runFrames({ url, count, intervalMs: stepMs, outDir, flags: parseFlags(argv.slice(7)) });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "hover": {
+        if (!url) die("missing url");
+        const sel = b; if (!sel) die("hover: missing <selector>");
+        const out = (c && !c.startsWith("--")) ? c : pickOutPath(argv.slice(6)) || makeOut(`hover-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`);
+        const r = await runHover({ url, selector: sel, out, flags: parseFlags(argv.slice(6)) });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "sweep": {
+        const planPath = readArg(a);
+        if (!planPath) die("sweep: missing <plan.json> (or @file)");
+        const outDirArg = (b && !b.startsWith("--")) ? b : undefined;
+        const r = await runSweep(planPath, outDirArg);
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "every-viewport": {
+        if (!url) die("missing url");
+        const outDir = (b && !b.startsWith("--")) ? b : undefined;
+        const viewports = c?.startsWith("--") ? undefined : c?.split(",");
+        const r = await runEveryViewport({ url, outDir, viewports });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "audit": {
+        if (!url) die("missing url");
+        const tags = (b && !b.startsWith("--")) ? b : undefined;
+        const outDir = (c && !c.startsWith("--")) ? c : undefined;
+        const r = await runAudit({ url, tags: tags?.split(",").map(t => t.trim()), outDir });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "dom-snapshot": case "dom": {
+        if (!url) die("missing url");
+        const out = (b && !b.startsWith("--")) ? b : undefined;
+        const r = await captureDomSnapshot({ url, out });
+        console.log(JSON.stringify({ url: r.url, title: r.title, elements: r.selectorMap?.length, domSize: r.dom?.length, out: r.url?.replace(/[^/]+$/, "") + "dom.json" }, null, 2));
+        break;
+      }
+      case "validate": {
+        const planPath = readArg(a);
+        if (!planPath) die("validate: missing <plan.json> (or @file)");
+        let plan;
+        try { plan = JSON.parse(readFile(planPath, "utf8")); }
+        catch (e) { die("validate: " + e.message); }
+        const { validateSweepPlan } = await import("../src/sweep-schema.js");
+        const v = validateSweepPlan(plan);
+        console.log(JSON.stringify({ valid: v.valid, errors: v.errors, plan: planPath }, null, 2));
+        if (!v.valid) process.exit(1);
+        break;
+      }
+      case "baseline": {
+        // pursor baseline <sub> [...args]
+        //   sub=list                    -> list baselines
+        //   sub=save <project> <png> <step>  [--id <id>] [--url <u>] [--meta-json <file>]
+        //   sub=approve <project> <png> <step>  [--id <id>] [--url <u>]
+        //   sub=show <project> <step>    [--id <id>] [--url <u>]
+        const sub = a;
+        const { saveBaseline, listBaselines, loadBaseline, approveBaseline, diffKey } = await import("../src/baseline.js");
+        if (sub === "list") {
+          // baseline list [project]
+          const project = b;
+          console.log(JSON.stringify(listBaselines(project), null, 2));
+        } else if (sub === "save") {
+          if (!b || !c || !d) die("baseline save: <project> <png> <step> [--id <id>] [--url <u>] [--meta-json <file>]");
+          const project = b, png = c, step = d;
+          const flags = parseFlags(argv.slice(7));
+          let meta = null;
+          if (flags["meta-json"]) meta = JSON.parse(readFile(flags["meta-json"], "utf8"));
+          else if (flags.url) meta = { url: flags.url };
+          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));
+        } else if (sub === "approve") {
+          if (!b || !c || !d) die("baseline approve: <project> <png> <step> [--id <id>] [--url <u>]");
+          const project = b, png = c, step = d;
+          const flags = parseFlags(argv.slice(7));
+          const id = flags.id || diffKey({ url: flags.url || "", flags: {} });
+          const result = approveBaseline({ project, id, step, fromPng: png });
+          console.log(JSON.stringify({ approved: true, ...result }, null, 2));
+        } else if (sub === "show") {
+          if (!b || !c) die("baseline show: <project> <step> [--id <id>] [--url <u>]");
+          const project = b, step = c;
+          const flags = parseFlags(argv.slice(5));
+          const id = flags.id || diffKey({ url: flags.url || "", flags: {} });
+          const r = loadBaseline({ project, id, step });
+          console.log(JSON.stringify(r, null, 2));
+        } else {
+          die("baseline subcommand: list | save | approve | show");
+        }
+        break;
+      }
+      case "auth": {
+              // pursor auth <sub> [...args]
+              //   save <project> <name> --from <state.json>
+              //   load <project> <name> --out <state.json>
+              //   list [project]
+              //   delete <project> <name>
+              const sub = a;
+              const { saveAuthState, loadAuthState, listAuthStates, deleteAuthState } = await import("../src/auth.js");
+              if (sub === "list") {
+                const project = b;
+                console.log(JSON.stringify(listAuthStates(project), null, 2));
+              } else if (sub === "save") {
+                if (!b || !c) die("auth save: <project> <name> --from <state.json>");
+                const fromFile = argv[argv.indexOf("--from") + 1];
+                if (!fromFile) die("auth save: missing --from <state.json>");
+                const state = JSON.parse(readFile(fromFile, "utf8"));
+                const r = saveAuthState({ project: b, name: c, state });
+                console.log(JSON.stringify({ saved: true, ...r }, null, 2));
+              } else if (sub === "load") {
+                if (!b || !c) die("auth load: <project> <name> --out <state.json>");
+                const outFile = argv[argv.indexOf("--out") + 1];
+                if (!outFile) die("auth load: missing --out <state.json>");
+                const state = loadAuthState({ project: b, name: c });
+                if (!state) { console.error("not found"); process.exit(2); }
+                writeFileSync(outFile, JSON.stringify(state, null, 2), "utf8");
+                console.log(JSON.stringify({ loaded: true, file: outFile, cookies: state.cookies.length, origins: state.origins.length }, null, 2));
+              } else if (sub === "delete") {
+                if (!b || !c) die("auth delete: <project> <name>");
+                const ok = deleteAuthState({ project: b, name: c });
+                console.log(JSON.stringify({ deleted: ok }, null, 2));
+              } else {
+                die("auth subcommand: list | save | load | delete");
+              }
+              break;
+            }
+            default: { die(`unknown subcommand: ${cmd}`); }
+    }
+  } catch (e) {
+    console.error(JSON.stringify({ error: e.message, stack: e.stack?.split("\n").slice(0, 3).join("\n") }, null, 2));
+    process.exit(1);
+  }
+})();

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "pursr",
+  "version": "0.4.0",
+  "private": false,
+  "description": "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",
+  "bugs": "https://github.com/0xheycat/pursr/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xheycat/pursr.git"
+  },
+  "funding": "https://github.com/sponsors/0xheycat",
+  "type": "module",
+  "bin": {
+    "pursr": "./bin/pursr.mjs",
+    "pursr-mcp": "./bin/pursr-mcp.mjs"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./plugin": "./src/plugin.js",
+    "./plugins/*": "./plugins/*.js",
+    "./util": "./src/util.js",
+    "./runway": "./src/runway.js",
+    "./selector": "./src/selector.js",
+    "./overlays": "./src/overlays.js",
+    "./viewport": "./src/viewport.js",
+    "./dom-snapshot": "./src/dom-snapshot.js",
+    "./plugin-audit": "./src/plugin-audit.js",
+    "./selector-heal": "./src/selector-heal.js",
+    "./ci-output": "./src/ci-output.js",
+    "./mcp": "./src/mcp.js",
+    "./baseline": "./src/baseline.js",
+    "./sweep-schema": "./src/sweep-schema.js",
+    "./mcp-resources": "./src/mcp-resources.js",
+    "./har": "./src/har.js",
+    "./auth": "./src/auth.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "plugins",
+    "plans",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/pursor.mjs",
+    "test": "node --test \"test/*.test.js\"",
+    "smoke": "node bin/pursor.mjs viewports"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "visual-qa",
+    "visual-regression",
+    "screenshot",
+    "audit",
+    "accessibility",
+    "axe-core",
+    "playwright",
+    "mcp",
+    "model-context-protocol",
+    "baseline",
+    "diff",
+    "har",
+    "testing",
+    "devtools",
+    "pursr"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "axe-core": "^4.12.1",
+    "pixelmatch": "^5.3.0",
+    "pngjs": "^7.0.0"
+  },
+  "peerDependencies": {
+    "playwright-core": "*"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "playwright-core": "^1.61.0"
+  }
+}

package/plans/m5.4-polish.json

@@ -0,0 +1,22 @@
+{
+  "name": "m5.4-polish",
+  "base": "http://localhost:3010",
+  "outDir": "./out/m54-sweep",
+  "steps": [
+    { "name": "baseline",         "shoot":  { "preset": "desktop-1280" } },
+    { "name": "cursor-pointer",   "shoot":  { "preset": "desktop-1280", "cursor": "pointer" } },
+    { "name": "grid-64",          "shoot":  { "preset": "desktop-1280", "grid": true, "grid-tile": 64 } },
+    { "name": "grid-128",         "shoot":  { "preset": "desktop-1280", "grid": true, "grid-tile": 128 } },
+    { "name": "layer-entity",     "shoot":  { "preset": "desktop-1280", "layer": "entity" } },
+    { "name": "layer-terrain",    "shoot":  { "preset": "desktop-1280", "layer": "terrain" } },
+    { "name": "no-hud",           "shoot":  { "preset": "desktop-1280", "no-hud": true } },
+    { "name": "frozen",           "shoot":  { "preset": "desktop-1280", "no-animation": true } },
+    { "name": "tablet-768",       "shoot":  { "preset": "tablet-768" } },
+    { "name": "mobile-375",       "shoot":  { "preset": "mobile-375" } },
+    { "name": "ultrawide-3440",   "shoot":  { "preset": "ultrawide-3440" } },
+    { "name": "hover-build",      "hover":  { "selector": "text=Build" } },
+    { "name": "hover-decor",      "hover":  { "selector": "text=Decor" } },
+    { "name": "frames-8",         "frames": { "count": 8, "intervalMs": 200 } },
+    { "name": "diff-vs-baseline", "diff":   { "ref": "baseline.png" } }
+  ]
+}

package/plugins/plugin-audit.js

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

package/plugins/plugin-demo.js

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

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; }
+}