aipeek 0.2.5 → 0.2.7

package/README.md

@@ -39,9 +39,10 @@ All endpoints are available on your Vite dev server:
 | `GET /__aipeek/{section}/{index}` | Detail for a specific item in a section |
 | `GET /__aipeek/{section}?full` | Full detail (no truncation) |
 | `GET /__aipeek/dom[?scope=Name\|?sel=css]` | Semantic DOM — UI as text (see below) |
+| `GET /__aipeek/query?sel=css` | Read-side twin of `sel=`: a selector's live `count` + each match's `text`/`visible`/`attrs` (role, `data-state`, `aria-*`/`data-*`, value, disabled). Per-element assertions without `/eval`. |
 | `GET /__aipeek/{action}?...` | Drive the page (see Actions) |
 | `POST /__aipeek/chain` | Run a JSON array of actions in one round-trip (see Actions) |
-| `GET\|POST /__aipeek/eval` | Run arbitrary JS in the page (`?code=` or POST body); returns the result. Escape hatch for what typed endpoints can't do. |
+| `GET\|POST /__aipeek/eval` | Run arbitrary JS in the page (`?code=` or POST body); returns the result. Escape hatch for what typed endpoints can't do — for count/text/state/attr checks reach for `/query` first. |
 
 ### Perception layers — UI as text, not pixels
 

package/dist/{chunk-X3HAXWFJ.js → chunk-37VLLZIU.js}

@@ -6,7 +6,7 @@ import { fileURLToPath } from "url";
 import { transformSync } from "esbuild";
 
 // src/core/action.ts
-var TYPES = ["click", "fill", "press", "wait", "screenshot"];
+var TYPES = ["click", "fill", "press", "wait", "screenshot", "realclick", "query"];
 function resolveAction(type, args) {
   if (!TYPES.includes(type))
     return { valid: false, error: `unknown action: ${type}` };
@@ -14,6 +14,8 @@ function resolveAction(type, args) {
   switch (type) {
     case "click":
       return hasTarget ? { valid: true } : { valid: false, error: "click needs sel= or text=" };
+    case "realclick":
+      return hasTarget || args.x !== void 0 && args.y !== void 0 ? { valid: true } : { valid: false, error: "realclick needs sel=, text=, or x= & y=" };
     case "fill":
       if (!hasTarget)
         return { valid: false, error: "fill needs sel= or text=" };
@@ -26,6 +28,8 @@ function resolveAction(type, args) {
       return hasTarget ? { valid: true } : { valid: false, error: "wait needs sel= or text=" };
     case "screenshot":
       return { valid: true };
+    case "query":
+      return args.sel ? { valid: true } : { valid: false, error: "query needs sel=" };
     default:
       return { valid: false, error: `unknown action: ${type}` };
   }
@@ -67,6 +71,47 @@ function check(raw) {
 function truncate(s, max) {
   return s.length > max ? `${s.slice(0, max)}\u2026` : s;
 }
+function formatValue(v, seen = /* @__PURE__ */ new Set()) {
+  if (v === null || v === void 0)
+    return String(v);
+  const t = typeof v;
+  if (t === "string")
+    return v;
+  if (t === "number" || t === "boolean" || t === "bigint")
+    return String(v);
+  if (t === "symbol")
+    return v.toString();
+  if (t === "function")
+    return `[Function: ${v.name || "anonymous"}]`;
+  const obj = v;
+  if (seen.has(obj))
+    return "[Circular]";
+  if (v instanceof Error)
+    return v.stack || `${v.name}: ${v.message}`;
+  seen.add(obj);
+  if (v instanceof Map) {
+    const items = [...v.entries()].slice(0, 15).map(([k, val]) => `${formatValue(k, seen)} => ${formatValue(val, seen)}`);
+    return `Map(${v.size}) {${items.join(", ")}${v.size > 15 ? ", \u2026" : ""}}`;
+  }
+  if (v instanceof Set) {
+    const items = [...v.values()].slice(0, 15).map((val) => formatValue(val, seen));
+    return `Set(${v.size}) {${items.join(", ")}${v.size > 15 ? ", \u2026" : ""}}`;
+  }
+  if (Array.isArray(v)) {
+    const items = v.slice(0, 30).map((val) => formatValue(val, seen));
+    return `[${items.join(", ")}${v.length > 30 ? ", \u2026" : ""}]`;
+  }
+  try {
+    return JSON.stringify(v);
+  } catch {
+    const entries = Object.entries(v).slice(0, 15);
+    const parts = entries.map(([k, val]) => `${k}: ${formatValue(val, seen)}`);
+    return `{${parts.join(", ")}}`;
+  }
+}
+function appStackFrames(stack, max) {
+  return stack.split("\n").map((l) => l.trim()).filter((l) => l.startsWith("at ") && !l.includes("node_modules") && !l.includes("<anonymous>")).slice(0, max);
+}
 function compactUrl(url, search) {
   try {
     const u = new URL(url);
@@ -283,17 +328,12 @@ function compactErrors(errors) {
   for (const err of seen.values()) {
     lines.push(err.message);
     if (err.stack) {
-      const frames = filterStack(err.stack);
-      for (const frame of frames) {
-        lines.push(`  at ${frame}`);
-      }
+      for (const frame of appStackFrames(err.stack, 5))
+        lines.push(`  ${frame}`);
     }
   }
   return lines.join("\n");
 }
-function filterStack(stack) {
-  return stack.split("\n").map((l) => l.trim()).filter((l) => l.startsWith("at ")).map((l) => l.slice(3)).filter((l) => !l.includes("node_modules") && !l.includes("<anonymous>")).slice(0, 5);
-}
 function compactState(state) {
   if (!state || !Object.keys(state).length)
     return "";
@@ -302,7 +342,7 @@ function compactState(state) {
     lines.push(`${name}:`);
     if (typeof value === "object" && value !== null) {
       for (const [k, v] of Object.entries(value)) {
-        lines.push(`  ${k}: ${formatValue(v)}`);
+        lines.push(`  ${k}: ${truncate(formatValue(v), 120)}`);
       }
     } else {
       lines.push(`  ${String(value)}`);
@@ -310,19 +350,6 @@ function compactState(state) {
   }
   return lines.join("\n");
 }
-function formatValue(v) {
-  if (v === null || v === void 0)
-    return String(v);
-  if (typeof v === "string")
-    return v;
-  if (typeof v === "number" || typeof v === "boolean")
-    return String(v);
-  if (typeof v === "object") {
-    const s = JSON.stringify(v);
-    return s.length > 120 ? `${s.slice(0, 120)}\u2026` : s;
-  }
-  return String(v);
-}
 function compact(raw) {
   return {
     url: raw.url,
@@ -459,12 +486,10 @@ function detailError(errors, index, full) {
   }
   const lines = [err.message];
   if (err.stack) {
-    const appFrames = err.stack.split("\n").map((l) => l.trim()).filter((l) => l.startsWith("at ") && !l.includes("node_modules")).slice(0, 3);
-    if (appFrames.length)
-      lines.push(...appFrames);
-    const totalApp = err.stack.split("\n").filter((l) => l.trim().startsWith("at ") && !l.includes("node_modules")).length;
-    if (totalApp > 3)
-      lines.push(`  ... ${totalApp - 3} more app frames`);
+    const all = appStackFrames(err.stack, Infinity);
+    lines.push(...all.slice(0, 3));
+    if (all.length > 3)
+      lines.push(`  ... ${all.length - 3} more app frames`);
   }
   if (err.line != null)
     lines.push(`location: ${err.source || ""}:${err.line}:${err.column ?? 0}`);
@@ -482,9 +507,9 @@ function detailState(state, name, full) {
   const value = state[name];
   if (full) {
     try {
-      return JSON.stringify(value, null, 2);
+      return JSON.stringify(value, null, 2) ?? formatValue(value);
     } catch {
-      return String(value);
+      return formatValue(value);
     }
   }
   if (typeof value !== "object" || value === null)
@@ -502,20 +527,9 @@ function isArraySentinel(v) {
   return digits.length > 0 && [...digits].every((c) => c >= "0" && c <= "9");
 }
 function formatSummaryValue(v) {
-  if (v === null || v === void 0)
-    return String(v);
-  if (typeof v === "string") {
-    if (isArraySentinel(v))
-      return v;
-    return v.length > 80 ? `${v.slice(0, 80)}\u2026` : v;
-  }
-  if (typeof v === "number" || typeof v === "boolean")
-    return String(v);
-  if (typeof v === "object") {
-    const s = JSON.stringify(v);
-    return s.length > 80 ? `${s.slice(0, 80)}\u2026` : s;
-  }
-  return String(v);
+  if (typeof v === "string" && isArraySentinel(v))
+    return v;
+  return truncate(formatValue(v), 80);
 }
 function jsonSchema(sample) {
   try {
@@ -749,6 +763,10 @@ function readBody(req) {
     req.on("end", () => resolve2(s));
   });
 }
+function send(res, status, body) {
+  res.writeHead(status, { "Content-Type": "text/plain; charset=utf-8" });
+  res.end(body);
+}
 var __dirname2 = dirname(fileURLToPath(import.meta.url));
 var clientDir = existsSync(resolve(__dirname2, "../client")) ? resolve(__dirname2, "../client") : resolve(__dirname2, "../src/client");
 var clientPath = resolve(clientDir, "client.ts");
@@ -783,8 +801,12 @@ curl ${base}/console  # console logs (errors, warnings, info)
 curl ${base}/network  # fetch/XHR requests with status and timing
 curl ${base}/errors   # uncaught errors and unhandled rejections
 curl ${base}/state    # registered store snapshots
+curl '${base}/query?sel=[role=menuitem]' # this selector right now: count + each element's text/visible/attrs
 \`\`\`
 
+\`/query\` is the read-side twin of click/fill's \`sel=\` \u2014 assert on a specific element
+(how many match, its text, \`data-state\`, \`aria-*\`/\`data-*\`, value, disabled) without \`/eval\`.
+
 \`/screen\` projects the whole UI to a few state variables \u2014 start there, not \`/ui\`. Append
 \`?full\` for untruncated output. Append \`/{index}\` for a specific item's detail.
 
@@ -821,34 +843,33 @@ curl -X POST ${base}/chain -d '[
 \`\`\`
 
 **Escape hatch.** \`curl '${base}/eval?code=...'\` (or POST the code as the body) runs arbitrary
-JS in the page and returns the result \u2014 for anything the typed endpoints can't do.
+JS in the page and returns the result \u2014 for what the typed endpoints can't do (install listeners,
+read closures, probe event flow). For count/text/state/attr assertions reach for \`/query\` first.
 
 aipeek auto-detects errors after HMR and prints them to the terminal \u2014 watch for \`[aipeek]\` messages.
 `;
 }
 var START_TAG = "<!-- AIPEEK:START -->";
 var END_TAG = "<!-- AIPEEK:END -->";
-function injectClaudeMd(root, port) {
-  const path = resolve(root, "CLAUDE.md");
+function renderClaudeMd(existing, port) {
   const block = `${START_TAG}
 ${aipeekSnippet(port).trim()}
 ${END_TAG}
 `;
+  if (existing === null)
+    return block;
+  const si = existing.indexOf(START_TAG);
+  const ei = existing.indexOf(END_TAG);
+  if (si !== -1 && ei !== -1)
+    return existing.slice(0, si) + block.trimEnd() + existing.slice(ei + END_TAG.length);
+  const sep = existing.endsWith("\n") ? "" : "\n";
+  return `${existing}${sep}
+${block}`;
+}
+function injectClaudeMd(root, port) {
+  const path = resolve(root, "CLAUDE.md");
   try {
-    if (!existsSync(path)) {
-      writeFileSync(path, block);
-      return;
-    }
-    const content = readFileSync(path, "utf-8");
-    const si = content.indexOf(START_TAG);
-    const ei = content.indexOf(END_TAG);
-    if (si !== -1 && ei !== -1) {
-      writeFileSync(path, content.slice(0, si) + block.trimEnd() + content.slice(ei + END_TAG.length));
-      return;
-    }
-    const sep = content.endsWith("\n") ? "" : "\n";
-    writeFileSync(path, `${content}${sep}
-${block}`);
+    writeFileSync(path, renderClaudeMd(existsSync(path) ? readFileSync(path, "utf-8") : null, port));
   } catch {
   }
 }
@@ -859,6 +880,27 @@ function aipeekPlugin() {
   let pushTimer;
   const pendingActions = /* @__PURE__ */ new Map();
   let actionId = 0;
+  const cdpQueue = [];
+  let cdpWaiter = null;
+  const cdpResults = /* @__PURE__ */ new Map();
+  let cdpId = 0;
+  function runCdpClick(x, y, button) {
+    const id = ++cdpId;
+    const cmd = { id, x, y, button };
+    return new Promise((resolve2, reject) => {
+      cdpResults.set(id, resolve2);
+      if (cdpWaiter) {
+        cdpWaiter(cmd);
+        cdpWaiter = null;
+      } else {
+        cdpQueue.push(cmd);
+      }
+      setTimeout(() => {
+        if (cdpResults.delete(id))
+          reject(new Error("cdp timeout: no extension result within 10s (is the aipeek extension loaded and the debugger attached?)"));
+      }, 1e4);
+    });
+  }
   let pendingDom = null;
   let pendingScreen = null;
   const pendingEvals = /* @__PURE__ */ new Map();
@@ -919,6 +961,18 @@ function aipeekPlugin() {
       };
     }, fullMs);
   }
+  async function runAction(type, args) {
+    const result = await sendAction(type, args);
+    lastRaw = null;
+    if (type === "realclick" && result.ok && result.ui === void 0) {
+      const cdp = await runCdpClick(result.x, result.y, args.button ?? "left");
+      if (!cdp.ok)
+        return { ok: false, error: `cdp click failed: ${cdp.error ?? "unknown"}` };
+      result.detail = `${result.detail} \u2192 clicked via extension`;
+      result.ui = await collectScreenFromClient();
+    }
+    return result;
+  }
   function evalInClient(code) {
     const id = ++evalId;
     return twoPhase("aipeek:eval", { id, code }, (resolve2) => {
@@ -1011,13 +1065,11 @@ function aipeekPlugin() {
             if (!code && req.method === "POST")
               code = await readBody(req);
             if (!code) {
-              res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
-              res.end("eval needs ?code= or a POST body");
+              send(res, 400, "eval needs ?code= or a POST body");
               return;
             }
             const r = await evalInClient(code);
-            res.writeHead(r.ok ? 200 : 422, { "Content-Type": "text/plain; charset=utf-8" });
-            res.end(r.ok ? r.value ?? "undefined" : `error: ${r.error}`);
+            send(res, r.ok ? 200 : 422, r.ok ? r.value ?? "undefined" : `error: ${r.error}`);
             return;
           }
           if (parts[0] === "dom") {
@@ -1025,14 +1077,50 @@ function aipeekPlugin() {
               url.searchParams.get("scope") || void 0,
               url.searchParams.get("sel") || void 0
             );
-            res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
-            res.end(dom || "(empty)");
+            send(res, 200, dom || "(empty)");
             return;
           }
           if (parts[0] === "screen") {
             const screen = await collectScreenFromClient();
-            res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
-            res.end(screen || "(empty)");
+            send(res, 200, screen || "(empty)");
+            return;
+          }
+          if (parts[0] === "cdp" && parts[1] === "poll") {
+            const queued = cdpQueue.shift();
+            if (queued) {
+              send(res, 200, JSON.stringify(queued));
+              return;
+            }
+            const cmd = await new Promise((resolve2) => {
+              cdpWaiter = resolve2;
+              setTimeout(() => {
+                if (cdpWaiter === resolve2) {
+                  cdpWaiter = null;
+                  resolve2(null);
+                }
+              }, 25e3);
+            });
+            if (cmd)
+              send(res, 200, JSON.stringify(cmd));
+            else
+              send(res, 204, "");
+            return;
+          }
+          if (parts[0] === "cdp" && parts[1] === "result") {
+            const body = await readBody(req);
+            let data;
+            try {
+              data = JSON.parse(body);
+            } catch {
+              send(res, 400, "cdp/result needs a JSON body {id, ok, error?}");
+              return;
+            }
+            const resolveCdp = cdpResults.get(data.id);
+            if (resolveCdp) {
+              cdpResults.delete(data.id);
+              resolveCdp({ ok: data.ok, error: data.error });
+            }
+            send(res, 200, "ok");
             return;
           }
           if (parts[0] === "chain") {
@@ -1043,8 +1131,7 @@ function aipeekPlugin() {
               if (!Array.isArray(steps))
                 throw new Error("body must be a JSON array");
             } catch (e) {
-              res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
-              res.end(`invalid chain body: ${e instanceof Error ? e.message : String(e)}`);
+              send(res, 400, `invalid chain body: ${e instanceof Error ? e.message : String(e)}`);
               return;
             }
             lastRaw = null;
@@ -1059,7 +1146,7 @@ function aipeekPlugin() {
                 allOk = false;
                 break;
               }
-              const r = await sendAction(type, args);
+              const r = await runAction(type, args);
               lines.push(`[${i}] ${r.ok ? "\u2713" : "\u2717"} ${type}: ${r.ok ? r.detail || "ok" : r.error}`);
               if (r.screen)
                 lines.push(r.screen.split("\n").map((l) => `    ${l}`).join("\n"));
@@ -1070,14 +1157,13 @@ function aipeekPlugin() {
                 break;
               }
             }
-            res.writeHead(allOk ? 200 : 422, { "Content-Type": "text/plain; charset=utf-8" });
-            res.end(lastUi ? `${lines.join("\n")}
+            send(res, allOk ? 200 : 422, lastUi ? `${lines.join("\n")}
 
 --- ui after ---
 ${lastUi}` : lines.join("\n"));
             return;
           }
-          if (["click", "fill", "press", "wait", "screenshot"].includes(parts[0])) {
+          if (["click", "fill", "press", "wait", "screenshot", "realclick", "query"].includes(parts[0])) {
             const q = url.searchParams;
             const args = {
               sel: q.get("sel") || void 0,
@@ -1085,31 +1171,30 @@ ${lastUi}` : lines.join("\n"));
               value: q.has("value") ? q.get("value") : void 0,
               key: q.get("key") || void 0,
               timeout: q.has("timeout") ? Number(q.get("timeout")) : void 0,
-              gone: q.has("gone") ? q.get("gone") !== "false" : void 0
+              gone: q.has("gone") ? q.get("gone") !== "false" : void 0,
+              button: q.get("button") === "right" ? "right" : q.get("button") === "left" ? "left" : void 0,
+              x: q.has("x") ? Number(q.get("x")) : void 0,
+              y: q.has("y") ? Number(q.get("y")) : void 0
             };
             const check2 = resolveAction(parts[0], args);
             if (!check2.valid) {
-              res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
-              res.end(check2.error);
+              send(res, 400, check2.error ?? "invalid action");
               return;
             }
-            const result = await sendAction(parts[0], args);
-            lastRaw = null;
+            const result = await runAction(parts[0], args);
             if (parts[0] === "screenshot" && result.dataUrl) {
               const dir = resolve(server.config.root, ".aipeek");
               mkdirSync(dir, { recursive: true });
               const name = q.get("out") || `shot-${result.dataUrl.length}.png`;
               const file = resolve(dir, name);
               writeFileSync(file, Buffer.from(result.dataUrl.split(",")[1], "base64"));
-              res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
-              res.end(`saved: ${file}`);
+              send(res, 200, `saved: ${file}`);
               return;
             }
-            res.writeHead(result.ok ? 200 : 422, { "Content-Type": "text/plain; charset=utf-8" });
             const head = result.ok ? result.detail || "ok" : `${result.error}${result.detail ? `
 
 clickable: ${result.detail}` : ""}`;
-            res.end(result.ui ? `${head}
+            send(res, result.ok ? 200 : 422, result.ui ? `${head}
 
 --- ui after ---
 ${result.ui}` : head);
@@ -1120,8 +1205,7 @@ ${result.ui}` : head);
             lastRaw = raw2;
             const result = check(raw2);
             const output = emitCheck(result);
-            res.writeHead(result.pass ? 200 : 417, { "Content-Type": "text/plain; charset=utf-8" });
-            res.end(output);
+            send(res, result.pass ? 200 : 417, output);
             return;
           }
           if (parts.length >= 1) {
@@ -1129,29 +1213,22 @@ ${result.ui}` : head);
               lastRaw = await collectFromClient();
             const result = detail(lastRaw, parts[0], parts[1], full);
             if (result !== null) {
-              res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
-              res.end(result);
+              send(res, 200, result);
               return;
             }
-            res.writeHead(404, { "Content-Type": "text/plain" });
-            res.end(`not found: ${parts.join("/")}`);
+            send(res, 404, `not found: ${parts.join("/")}`);
             return;
           }
           const raw = await collectFromClient();
           lastRaw = raw;
           if (full) {
             const compacted = compact(raw);
-            const output = emit(compacted);
-            res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
-            res.end(output);
+            send(res, 200, emit(compacted));
           } else {
-            const output = emitSummary(raw);
-            res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
-            res.end(output);
+            send(res, 200, emitSummary(raw));
           }
         } catch (err) {
-          res.writeHead(504, { "Content-Type": "text/plain" });
-          res.end(err instanceof Error ? err.message : "unknown error");
+          send(res, 504, err instanceof Error ? err.message : "unknown error");
         }
       });
     }
@@ -1166,6 +1243,7 @@ export {
   emitDiff,
   START_TAG,
   END_TAG,
+  renderClaudeMd,
   injectClaudeMd,
   aipeekPlugin
 };