pursr 0.10.0 → 0.10.1

package/README.md

@@ -154,7 +154,16 @@ pursr baseline approve myapp ./new.png home --url https://example.com
 pursr validate ./plan.json
 ```
 
-### Subcommands
+### Subcommands
+
+Flags are order-independent. Both commands below are valid, and explicit output paths override Pursr's default output directory:
+
+```bash
+pursr shot --preset desktop-1280 https://example.com --out ./captures/home.png
+pursr full https://example.com --preset desktop-1280 --out-dir ./captures
+```
+
+`--out` is a complete file path. `--out-dir` is a directory where Pursr writes the command's standard filename.
 
 | Subcommand | Purpose |
 | --- | --- |
@@ -175,7 +184,11 @@ pursr validate ./plan.json
 | `every-viewport` | Capture once per preset in parallel (3-wide pool) |
 | `baseline` | save / list / approve / show visual baselines |
 | `auth` | save / load / list / delete Playwright storageState |
-| `validate` | Validate a sweep plan JSON without running it |
+| `validate` | Validate a sweep plan JSON without running it |
+
+### Agent Skill
+
+The npm package includes [`SKILL.md`](./SKILL.md), a compact operating guide for coding agents. Point an agent at `node_modules/pursr/SKILL.md`, or copy it into the skill directory used by your agent host. It explains when to use CLI versus MCP, correct argument order, action plans, visual verification, and safety boundaries.
 
 ## MCP Server
 

package/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: pursr
+description: Use Pursr for browser screenshots, scripted visual operation, visual regression, accessibility audits, DOM inspection, and MCP-driven browser sessions.
+---
+
+# Pursr
+
+Use this skill when a user asks an agent to inspect, operate, record, test, or compare a browser interface.
+
+## Choose The Right Surface
+
+- Use the CLI for repeatable commands and prewritten action plans.
+- Use MCP when the agent must inspect the current page, choose the next action, verify it, or pause for human approval.
+- Use `pursr operator` for a visible scripted walkthrough or silent WebM recording.
+- Use `pursr shoot` for a rich screenshot with viewport, layer, camera, grid, or animation controls.
+- Use `pursr check` for CI regression against an approved baseline.
+- Use `pursr sweep` only with a local JSON plan path. A URL is not a sweep plan.
+
+## CLI Argument Contract
+
+Flags may appear before or after positional arguments.
+
+```bash
+pursr shot --preset desktop-1280 https://example.com --out ./out/page.png
+pursr full https://example.com --out-dir ./out
+pursr eval --preset desktop-1280 https://example.com "document.title" --out ./out/eval.png
+pursr click https://example.com "role=button|Continue" --out ./out/click.png
+pursr type https://example.com "#email" "hello@example.com" --out ./out/type.png
+pursr hover https://example.com "text=Pricing" --out ./out/hover.png
+pursr seq https://example.com ./actions.json --out ./out/final.png
+pursr sweep ./sweep-plan.json --out-dir ./out/sweep
+```
+
+`--out` is a complete file path. `--out-dir` is a directory; Pursr chooses the command's standard filename inside it.
+
+For `seq` and `operator`, actions may be inline JSON, a plain `.json` path, or an `@file.json` reference.
+
+## Visual Operator
+
+```bash
+pursr operator https://example.com ./actions.json \
+  --visible --start-delay 1500 --slow-mo 80 \
+  --video ./recordings --out ./recordings/final.png
+```
+
+The result includes the action trace, final screenshot, diagnostics, and WebM path. Browser video is silent.
+
+Common actions:
+
+```json
+[
+  { "type": "annotate", "selector": "role=button|Continue", "label": "Continue" },
+  { "type": "click", "selector": "role=button|Continue" },
+  { "type": "fill", "selector": "#email", "text": "hello@example.com" },
+  { "type": "drag", "fromX": 200, "fromY": 300, "toX": 600, "toY": 300 },
+  { "type": "press", "key": "Escape" }
+]
+```
+
+## MCP Agent Loop
+
+1. Open one stable session with `pursr_session_open`.
+2. Read rendered state with `pursr_snapshot`.
+3. Perform a small action sequence with `pursr_act`.
+4. Use `pursr_screenshot` when visual judgment is needed.
+5. Use `pursr_inspect` for geometry, clipping, style, or stacking issues.
+6. Read `pursr_diagnostics` after failures.
+7. Close with `pursr_session_close`; this finalizes any video recording.
+
+## Safety
+
+- Inspect before acting on unfamiliar pages.
+- Ask for human confirmation immediately before publishing, sending, purchasing, deleting, or changing permissions.
+- Keep CDP endpoints on localhost. CDP preserves the browser profile but cannot record video.
+- Do not claim a visual result passed until the produced screenshot or video has been checked.
+
+## Avoid
+
+- Do not pass a URL to `sweep`; pass a JSON plan file.
+- Do not treat `viewports` as a capture command; it only lists presets.
+- Do not use `probe` as visual evidence; it only returns HTTP and page metadata.
+- Do not invent selectors. Snapshot or inspect the page first when using MCP.

package/bin/pursr.mjs

@@ -16,9 +16,10 @@ 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, __PURSR_GET } from "../src/util.js";
+import { asNum, readArg, makeOut, __PURSR_GET } from "../src/util.js";
+import { filePathArg, parseCommandArgs } from "../src/cli-args.js";
 import { writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { readFileSync as _readFileSync } from "node:fs";
 const readFile = _readFileSync;
 import { loadPlugins, listPlugins, getFlagHelp } from "../src/plugin.js";
@@ -44,19 +45,24 @@ function die(msg, code = 2) {
   process.exit(code);
 }
 
-const argv = process.argv;
-const [, , cmd, a, b, c, d] = argv;
-const url = __PURSR_GET("PURSR_URL") || a;
-// Top-level --plan / --out parsing for subcommands that need it before dispatch
-function _topOpts() {
-  const o = {};
-  for (let i = 2; i < argv.length; i++) {
-    if (argv[i] === "--plan" && i + 1 < argv.length) o.plan = argv[++i];
-    if (argv[i] === "--out" && i + 1 < argv.length) o.out = argv[++i];
-  }
-  return o;
-}
-const opts = _topOpts();
+const argv = process.argv;
+const [, , cmd] = argv;
+const { flags: cliFlags, positionals } = parseCommandArgs(argv.slice(3));
+const [a, b, c, d] = positionals;
+const url = __PURSR_GET("PURSR_URL") || a;
+const opts = { plan: cliFlags.plan, out: cliFlags.out };
+
+function outputPath(positional, filename) {
+  if (cliFlags.out) return String(cliFlags.out);
+  if (positional) return positional;
+  if (cliFlags["out-dir"]) return join(String(cliFlags["out-dir"]), filename);
+  return makeOut(filename);
+}
+
+function dataArg(value) {
+  if (value && !value.startsWith("@") && existsSync(value)) return readFile(value, "utf8").replace(/\r?\n$/, "");
+  return readArg(value);
+}
 
 // Plugin loading: scan for --plugin <path> and built-in plugins/
 const pluginPaths = [];
@@ -64,40 +70,41 @@ for (let i = 0; i < argv.length; i++) if (argv[i] === "--plugin" && i + 1 < argv
 await loadPlugins(pluginPaths);
 
 (async () => {
-  try {
-    switch (cmd) {
+  try {
+    if (cliFlags.help) { console.log(JSON.stringify({ usage: USAGE }, null, 2)); return; }
+    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: "pursr", 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 "shot": { if (!url) die("missing url"); const out = outputPath(b, "shot.png"); const r = await runShot(url, out, { ...cliFlags, fullPage: false }); console.log(JSON.stringify(r, null, 2)); break; }
+      case "full": { if (!url) die("missing url"); const out = outputPath(b, "full.png"); const r = await runShot(url, out, { ...cliFlags, fullPage: true }); console.log(JSON.stringify(r, null, 2)); break; }
+      case "eval": { if (!url) die("missing url"); const js = dataArg(b); if (!js) die("eval: missing <js> (or @file)"); const out = outputPath(c, "eval.png"); const r = await runEval(url, js, out, cliFlags); 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 = outputPath(c, `click-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runClick(url, sel, out, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
+      case "type": { if (!url) die("missing url"); const sel = b; const text = dataArg(c); if (!sel || text === undefined) die("type: missing <selector> or <text> (text can be @file)"); const out = outputPath(d, `type-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runType(url, sel, text, out, cliFlags); 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, cliFlags); 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 flags = parseFlags(argv.slice(5));
+        const out = outputPath(c, "diff.png"); const threshold = cliFlags.threshold !== undefined ? Number(cliFlags.threshold) : d !== undefined ? Number(d) : 0.1;
+        const flags = { ...cliFlags };
         // --ai / --ai-model / --ai-base-url / --ai-api-key
         const useAi = argv.includes("--ai");
-        const aiModel = (() => { const i = argv.indexOf("--ai-model"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
-        const aiBaseUrl = (() => { const i = argv.indexOf("--ai-base-url"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
-        const aiApiKey = (() => { const i = argv.indexOf("--ai-api-key"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
+        const aiModel = cliFlags["ai-model"];
+        const aiBaseUrl = cliFlags["ai-base-url"];
+        const aiApiKey = cliFlags["ai-api-key"];
         const r = useAi
           ? await runDiffWithAi(url, ref, out, threshold, flags, { model: aiModel, baseUrl: aiBaseUrl, apiKey: aiApiKey })
           : await runDiff(url, ref, out, threshold, flags);
         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 "seq": { if (!url) die("missing url"); const actions = dataArg(b); if (!actions) die("seq: missing <actions.json> (or @file)"); const out = outputPath(c, "seq.png"); const r = await runSeq(url, actions, out, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
       case "operator": {
         if (!url) die("operator: missing <url>");
-        const actions = readArg(b); if (!actions) die("operator: missing <actions.json> (or @file)");
-        const flags = parseFlags(argv.slice(5));
-        const out = flags.out || makeOut("operator.png");
+        const actions = dataArg(b); if (!actions) die("operator: missing <actions.json> (or @file)");
+        const flags = { ...cliFlags };
+        const out = outputPath(null, "operator.png");
         const videoValue = flags.video ?? flags["record-video"];
         const recordVideoDir = videoValue
           ? (videoValue === true ? dirname(out) : String(videoValue))
@@ -130,16 +137,16 @@ await loadPlugins(pluginPaths);
       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)) });
+        const out = outputPath(b, "shoot.png");
+        const r = await runShootWithSidecar({ url, out, flags: { ...cliFlags } });
         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 out = outputPath(c, `layer-${layerName}.png`);
+        const flags = { ...cliFlags, layer: layerName };
         const r = await runShootWithSidecar({ url, out, flags });
         console.log(JSON.stringify(r, null, 2));
         break;
@@ -148,71 +155,70 @@ await loadPlugins(pluginPaths);
         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)) });
+        const outDir = cliFlags["out-dir"] || cliFlags.out || d || makeOut(`frames-${count}x${stepMs}ms`);
+        const r = await runFrames({ url, count, intervalMs: stepMs, outDir, flags: { ...cliFlags } });
         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)) });
+        const out = outputPath(c, `hover-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`);
+        const r = await runHover({ url, selector: sel, out, flags: { ...cliFlags } });
         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 planPath = filePathArg(a);
+        if (!planPath) die("sweep: missing <plan.json>");
+        if (/^https?:\/\//i.test(planPath)) die("sweep: expected a local JSON plan path, not a URL");
+        const outDirArg = cliFlags["out-dir"] || cliFlags.out || b;
         const r = await runSweep(planPath, outDirArg);
         console.log(JSON.stringify(r, null, 2));
         break;
       }
       case "report": {
         // pursr report --sweep <sweep.json> [--out report.pdf] [--title "..."]
-        const sweepIdx = argv.indexOf("--sweep");
-        const sweepPath = sweepIdx >= 0 && sweepIdx + 1 < argv.length ? argv[sweepIdx + 1] : a;
+        const sweepPath = cliFlags.sweep || a;
         if (!sweepPath) die("report: missing --sweep <sweep.json>");
         if (!existsSync(sweepPath)) die("report: sweep not found: " + sweepPath);
-        const outIdx = argv.indexOf("--out");
-        const outPath = outIdx >= 0 && outIdx + 1 < argv.length ? argv[outIdx + 1] : (opts.out || makeOut("report.pdf").replace(/pursr-[^-]+-shot.png$/, "report.pdf"));
+        const outPath = cliFlags.out || makeOut("report.pdf").replace(/pursr-[^-]+-shot.png$/, "report.pdf");
         if (outPath && outPath !== "-") mkdirSync(dirname(outPath), { recursive: true });
-        const titleIdx = argv.indexOf("--title");
-        const title = titleIdx >= 0 && titleIdx + 1 < argv.length ? argv[titleIdx + 1] : undefined;
-        const noEmbed = argv.includes("--no-embed");
+        const title = cliFlags.title;
+        const noEmbed = !!cliFlags["no-embed"];
         const summary = JSON.parse(readFile(sweepPath, "utf8"));
         const { renderSweepPdf } = await import("../src/report.js");
         const buf = await renderSweepPdf(summary, { out: outPath === "-" ? undefined : outPath, title, embedImages: !noEmbed });
         console.log(JSON.stringify({ ok: true, sweep: sweepPath, out: outPath, bytes: buf.length }, 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(",");
+      case "every-viewport": {
+        if (!url) die("missing url");
+        const outDir = cliFlags["out-dir"] || cliFlags.out || b;
+        const viewports = 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;
+      case "audit": {
+        if (!url) die("missing url");
+        const tags = cliFlags.tags || b;
+        const outDir = cliFlags["out-dir"] || cliFlags.out || c;
         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;
+      case "dom-snapshot": case "dom": {
+        if (!url) die("missing url");
+        const out = cliFlags.out || b;
         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)");
+      case "validate": {
+        const planPath = filePathArg(a);
+        if (!planPath) die("validate: missing <plan.json>");
+        if (/^https?:\/\//i.test(planPath)) die("validate: expected a local JSON plan path, not a URL");
         let plan;
         try { plan = JSON.parse(readFile(planPath, "utf8")); }
         catch (e) { die("validate: " + e.message); }
@@ -237,7 +243,7 @@ await loadPlugins(pluginPaths);
         } 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));
+          const flags = { ...cliFlags };
           let meta = null;
           if (flags["meta-json"]) meta = JSON.parse(readFile(flags["meta-json"], "utf8"));
           else if (flags.url) meta = { url: flags.url };
@@ -253,14 +259,14 @@ await loadPlugins(pluginPaths);
         } 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 flags = { ...cliFlags };
           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 flags = { ...cliFlags };
           const id = flags.id || diffKey({ url: flags.url || "", flags: {} });
           const r = loadBaseline({ project, id, step });
           console.log(JSON.stringify(r, null, 2));
@@ -282,14 +288,14 @@ await loadPlugins(pluginPaths);
                 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];
+                const fromFile = cliFlags.from;
                 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];
+                const outFile = cliFlags.out;
                 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); }
@@ -312,9 +318,9 @@ await loadPlugins(pluginPaths);
                 die("watch: missing <url> (or use --plan <plan.json>)");
               }
               const { startWatch } = await import("../src/watch.js");
-              const out = (b && !b.startsWith("--")) ? b : (opts.out || makeOut("watch.png"));
+              const out = opts.out || b || makeOut("watch.png");
               if (out && out !== "--plan") mkdirSync(dirname(out), { recursive: true });
-              const flags = parseFlags(argv.slice(3));
+              const flags = { ...cliFlags };
               const onGlobs = [];
               for (let i = 0; i < argv.length; i++) {
                 if (argv[i] === "--on" && i + 1 < argv.length) onGlobs.push(argv[++i]);
@@ -341,9 +347,9 @@ await loadPlugins(pluginPaths);
               // pursr snap <url> <selector> [--out <dir>] [--name <slug>] [--max N] [--baseline <project>]
               if (!url) die("snap: missing <url>");
               const sel = b; if (!sel) die("snap: missing <selector>");
-              const flags = parseFlags(argv.slice(4));
+              const flags = { ...cliFlags };
               const { runSnap, approveSnapsAsBaselines } = await import("../src/snap.js");
-              const outDir = flags.out || makeOut("snaps").replace(/pursr-[^-]+-snap\.png$/, "snaps");
+              const outDir = flags["out-dir"] || flags.out || makeOut("snaps").replace(/pursr-[^-]+-snap\.png$/, "snaps");
               const snap = await runSnap({ url, selector: sel, outDir, name: flags.name, max: flags.max, flags });
               console.log(JSON.stringify({
                 url: snap.url,
@@ -363,7 +369,7 @@ await loadPlugins(pluginPaths);
             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 flags = { ...cliFlags };
               const update = !!flags.update;
               const threshold = flags.threshold !== undefined ? Number(flags.threshold) : 0.1;
               const { runCheck } = await import("../src/check.js");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pursr",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "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",
@@ -49,6 +49,7 @@
     "plugins",
     "plans",
     "assets",
+    "SKILL.md",
     "README.md",
     "LICENSE"
   ],

package/src/cli-args.js

@@ -0,0 +1,33 @@
+// Order-independent CLI argument parsing for pursr subcommands.
+
+const DEFAULT_BOOLEAN_FLAGS = new Set([
+  "ai", "full", "grid", "help", "json", "no-animation", "no-embed",
+  "no-hud", "no-visual", "update", "visible",
+]);
+
+export function parseCommandArgs(args = [], { booleanFlags = DEFAULT_BOOLEAN_FLAGS } = {}) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i];
+    if (!token?.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+
+    const eq = token.indexOf("=");
+    const key = token.slice(2, eq >= 0 ? eq : undefined);
+    let value;
+    if (eq >= 0) value = token.slice(eq + 1);
+    else if (booleanFlags.has(key)) value = true;
+    else if (i + 1 < args.length && !args[i + 1].startsWith("--")) value = args[++i];
+    else value = true;
+    flags[key] = value;
+  }
+  return { flags, positionals };
+}
+
+export function filePathArg(value) {
+  if (typeof value !== "string") return value;
+  return value.startsWith("@") ? value.slice(1) : value;
+}

package/src/diff.js

@@ -1,6 +1,6 @@
 // Pixelmatch diff against a reference PNG.
 
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { launch, newPage } from "./runway.js";
 import { resolveViewport } from "./viewport.js";
@@ -24,7 +24,8 @@ export async function runDiff(url, refPath, out, threshold, flags = {}, browser)
   requireArg("url", url, "string");
   requireArg("refPath", refPath, "string");
   const t = threshold !== undefined ? Number(threshold) : DIFF_DEFAULT_THRESHOLD;
-  if (!existsSync(refPath)) return { url, refPath, error: "reference file not found" };
+  if (!existsSync(refPath)) return { url, refPath, error: "reference file not found" };
+  if (out) mkdirSync(dirname(out), { recursive: true });
   const PNG = await loadPngjs();
   const pixelmatch = await loadPixelmatch();
   const ownBrowser = !browser;

package/src/eval.js

@@ -1,18 +1,24 @@
 // Evaluate a JS string in the page, optionally screenshot after.
 
 import { launch, newPage } from "./runway.js";
-import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { resolveViewport } from "./viewport.js";
 import { gotoOrThrow } from "./overlays.js";
-import { requireArg } from "./util.js";
+import { requireArg } from "./util.js";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 
-export async function runEval(url, js, out) {
-  requireArg("url", url, "string");
-  const browser = await launch();
-  try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+export async function runEval(url, js, out, flags = {}) {
+  requireArg("url", url, "string");
+  const viewport = resolveViewport(flags);
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, viewport);
     const r = await gotoOrThrow(page, url);
     const result = await page.evaluate(js);
-    if (out) await page.screenshot({ path: out, fullPage: false });
-    return { ...r, url, out, result };
+    if (out) {
+      mkdirSync(dirname(out), { recursive: true });
+      await page.screenshot({ path: out, fullPage: false });
+    }
+    return { ...r, url, out, viewport, result };
   } finally { try { await browser.close(); } catch {} }
-}
+}

package/src/hover.js

@@ -4,7 +4,9 @@ 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";
+import { asNum, asBool, nowIso, writeSidecar, requireArg } from "./util.js";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 
 export async function runHover({ url, selector, out, flags = {} }) {
   requireArg("url", url, "string");
@@ -18,9 +20,12 @@ export async function runHover({ url, selector, out, flags = {} }) {
     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) });
+    if (out) {
+      mkdirSync(dirname(out), { recursive: true });
+      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/interact.js

@@ -1,50 +1,56 @@
 // click, type, wait, seq — interaction primitives.
 
 import { launch, newPage } from "./runway.js";
-import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { resolveViewport } 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";
+import { requireArg } from "./util.js";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+function ensureScreenshotDir(out) {
+  if (out) mkdirSync(dirname(out), { recursive: true });
+}
 
-export async function runClick(url, selector, out) {
+export async function runClick(url, selector, out, flags = {}) {
   requireArg("url", url, "string");
   requireArg("selector", selector, "string");
   const browser = await launch();
   try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const page = await newPage(browser, resolveViewport(flags));
     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 });
+    if (out) { ensureScreenshotDir(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) {
+export async function runType(url, selector, text, out, flags = {}) {
   requireArg("url", url, "string");
   requireArg("selector", selector, "string");
   const browser = await launch();
   try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const page = await newPage(browser, resolveViewport(flags));
     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 });
+    if (out) { ensureScreenshotDir(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) {
+export async function runWait(url, selector, timeoutMs, flags = {}) {
   requireArg("url", url, "string");
   requireArg("selector", selector, "string");
   const browser = await launch();
   try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const page = await newPage(browser, resolveViewport(flags));
     const r = await gotoOrThrow(page, url);
     const loc = await resolveLocator(page, selector);
     const t = timeoutMs || WAIT_DEFAULT_TIMEOUT_MS;
@@ -57,7 +63,7 @@ export async function runWait(url, selector, timeoutMs) {
   } finally { try { await browser.close(); } catch {} }
 }
 
-export async function runSeq(url, actionsJson, out) {
+export async function runSeq(url, actionsJson, out, flags = {}) {
   requireArg("url", url, "string");
   let actions;
   try { actions = JSON.parse(actionsJson); }
@@ -66,7 +72,7 @@ export async function runSeq(url, actionsJson, out) {
   if (!actions.length) throw new Error("actions array is empty");
   const browser = await launch();
   try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const page = await newPage(browser, resolveViewport(flags));
     const r = await gotoOrThrow(page, url); await settle(page);
     const trace = [];
     let failed = false;
@@ -132,7 +138,7 @@ export async function runSeq(url, actionsJson, out) {
       trace.push(step);
       if (failed) break;
     }
-    if (out) await page.screenshot({ path: out, fullPage: false });
+    if (out) { ensureScreenshotDir(out); await page.screenshot({ path: out, fullPage: false }); }
     return { ...r, url, out, steps: trace, failed };
   } finally { try { await browser.close(); } catch {} }
-}
+}

package/src/shoot.js

@@ -10,10 +10,13 @@ import {
 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";
+import { loadAuthState } from "./auth.js";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 
-export async function runShoot({ url, out, flags = {}, prepare, browser: extBrowser }) {
-  requireArg("url", url, "string");
+export async function runShoot({ url, out, flags = {}, prepare, browser: extBrowser }) {
+  requireArg("url", url, "string");
+  if (out) mkdirSync(dirname(out), { recursive: true });
   const viewport = resolveViewport(flags);
   const ownBrowser = !extBrowser;
   const browser = extBrowser || await launch();
@@ -71,4 +74,4 @@ export async function runShootWithSidecar(args) {
   const meta = await runShoot(args);
   await writeSidecar(meta);
   return meta;
-}
+}

package/src/shot.js

@@ -1,18 +1,22 @@
 // Simple screenshot (no flags / overlays).
 
 import { launch, newPage } from "./runway.js";
-import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { resolveViewport } from "./viewport.js";
 import { gotoOrThrow, settle } from "./overlays.js";
-import { requireArg } from "./util.js";
+import { requireArg } from "./util.js";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 
-export async function runShot(url, out, opts = {}) {
-  requireArg("url", url, "string");
-  const browser = await launch();
-  try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+export async function runShot(url, out, opts = {}) {
+  requireArg("url", url, "string");
+  const viewport = resolveViewport(opts);
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, viewport);
     const r = await gotoOrThrow(page, url);
     await settle(page);
-    await page.screenshot({ path: out, fullPage: !!opts.fullPage });
-    return { ...r, url, out, fullPage: !!opts.fullPage };
+    if (out) mkdirSync(dirname(out), { recursive: true });
+    await page.screenshot({ path: out, fullPage: !!opts.fullPage });
+    return { ...r, url, out, viewport, fullPage: !!opts.fullPage };
   } finally { try { await browser.close(); } catch {} }
-}
+}