@botim/mp-debug-sdk 0.4.1 → 0.6.1

package/README.md

@@ -8,7 +8,7 @@ Mini-programs run on user devices in environments you can't easily attach a debu
 
 - **Live logs** of `console.*`, `fetch`, `XMLHttpRequest`, and uncaught errors.
 - **AI-observable sessions** — every event indexed by `(miniProgramId, deviceId, sid)` so resolver agents can pull errors and reproduce bugs without a human in the loop.
-- **Safe AI command channel** — agents can `reload`, `dump-state`, `set-feature-flag`, `screenshot`, `ping`, or any custom command you allow. Anything not registered is rejected.
+- **Safe AI command channel** — agents can `reload`, `dump-state`, `set-feature-flag`, `screenshot`, `ping`, `exec` (default-on remote REPL), or any custom command you allow. Anything not registered is rejected.
 - **Built-in redaction** before the event ever enters the in-memory buffer.
 
 ## Install
@@ -128,7 +128,58 @@ The SDK posts directly to `endpoint` — there's no proxy required. Your relay m
 CORS_ORIGINS=https://my-mp.example.com,https://staging.example.com
 ```
 
-## 5. Custom commands (optional)
+## 5. Remote REPL (`exec`) — default-on
+
+Once `enableRemoteDebug` returns, an attached agent can send a JS snippet to the device and read back the value, captured `console.*` output, or thrown error. No host wiring needed.
+
+```bash
+# From any terminal that can reach your relay:
+curl -sX POST "https://debug.botim.dev/v1/mp/<MP_ID>/devices/<DEVICE_ID>/commands" \
+  -H 'content-type: application/json' \
+  -d '{"name":"exec","args":{"code":"console.log(\"hi\"); return window.location.href"}}'
+```
+
+Result event:
+
+```jsonc
+{
+  "type": "command-ack",
+  "payload": {
+    "command": "exec",
+    "ok": true,
+    "result": {
+      "value": "https://my-mp.example.com/page",
+      "logs": [{"method":"log","args":["hi"],"ts": 1735324800123}],
+      "durationMs": 2
+    }
+  }
+}
+```
+
+Inside the snippet, `BOT`, `window`, and `document` are bound as locals (with `BOT` resolved best-effort from `window.BOT` or Angular DI; `null` if unavailable). Top-level `await` works. Code is capped at 8 KB and 30 s.
+
+**To opt out** (e.g. you ship a non-debug release that still uses the SDK for telemetry only):
+
+```ts
+await enableRemoteDebug({
+  // ...,
+  builtins: { exec: false },
+});
+```
+
+**To inject extra locals** for your app:
+
+```ts
+await enableRemoteDebug({
+  // ...,
+  builtins: { exec: { globals: { app: myApp, store: myStore } } },
+});
+// agent can then call: { code: "return store.getState().user" }
+```
+
+> Pre-buffer redaction (headers, JWT/long-token regex) is applied to `result.value` and `result.logs` before they leave the device buffer. The existing prod consent gate (`hostToken` or `userOptIn`) gates whether attach happens at all. See `docs/recipes/exec.md` for deeper notes.
+
+## 6. Custom commands (optional)
 
 Any AI agent with the right scope can request a command. The SDK only runs commands registered via `registerCommand`:
 
@@ -147,7 +198,7 @@ handle.registerCommand('set-locale', async (args) => {
 
 Anything not registered gets a `command-rejected` event with reason `unknown-command`.
 
-## 6. Lifecycle
+## 7. Lifecycle
 
 ```ts
 await handle.flush();    // force-send buffered events

package/dist/index.cjs

@@ -272,7 +272,7 @@ function resolveAgainstEndpoint(url, base) {
 function detectDeviceInfo(app, override) {
   const ua = typeof navigator !== "undefined" ? navigator.userAgent : void 0;
   return {
-    deviceId: override?.deviceId ?? generateDeviceId(),
+    deviceId: override?.deviceId ?? loadOrCreateDeviceId(),
     platform: override?.platform ?? detectPlatform(ua),
     osVersion: override?.osVersion,
     appName: override?.appName ?? app.name,
@@ -288,6 +288,21 @@ function detectPlatform(ua) {
   if (/Mozilla|Chrome|Safari|Firefox/i.test(ua)) return "web";
   return "unknown";
 }
+var DEVICE_ID_STORAGE_KEY = "botim-debug-sdk:device-id";
+function loadOrCreateDeviceId() {
+  try {
+    const ls = typeof localStorage !== "undefined" ? localStorage : null;
+    if (ls) {
+      const stored = ls.getItem(DEVICE_ID_STORAGE_KEY);
+      if (stored && stored.length > 0) return stored;
+      const fresh = generateDeviceId();
+      ls.setItem(DEVICE_ID_STORAGE_KEY, fresh);
+      return fresh;
+    }
+  } catch {
+  }
+  return generateDeviceId();
+}
 function generateDeviceId() {
   const c = typeof crypto !== "undefined" ? crypto : void 0;
   if (c?.randomUUID) return c.randomUUID();
@@ -562,6 +577,11 @@ function wrapFetch(opts) {
         method,
         url,
         status: res.status,
+        // statusText carries the human label ("OK", "Not Found"). Pre-HTTP/2
+        // responses always have it; HTTP/2+ defines it as empty by spec but
+        // most browsers synthesize one from the code, so this is reliable
+        // enough to display alongside the status code.
+        statusText: res.statusText || void 0,
         durationMs: Date.now() - start,
         resHeaders: headersFromResponse(res),
         resBody
@@ -575,7 +595,14 @@ function wrapFetch(opts) {
         url,
         durationMs: Date.now() - start,
         errorMessage: err instanceof Error ? err.message : String(err),
-        errorName: err instanceof Error ? err.name : void 0
+        errorName: err instanceof Error ? err.name : void 0,
+        // Stack from the rejected promise — points into fetch internals
+        // and (when present) the call site that issued the request.
+        errorStack: err instanceof Error ? err.stack : void 0,
+        // undici frequently wraps the real reason in `cause` (e.g.
+        // `TypeError: fetch failed` outside, `Error: ECONNREFUSED` inside).
+        // Flatten the chain so operators don't have to dig.
+        errorCause: collectCauseChain(err)
       });
       throw err;
     }
@@ -584,6 +611,24 @@ function wrapFetch(opts) {
     target.fetch = original;
   };
 }
+function collectCauseChain(err) {
+  if (!err || typeof err !== "object") return void 0;
+  const lines = [];
+  let cur = err.cause;
+  const seen = /* @__PURE__ */ new Set();
+  while (cur && lines.length < 5) {
+    if (seen.has(cur)) break;
+    seen.add(cur);
+    if (cur instanceof Error) {
+      lines.push(`${cur.name}: ${cur.message}`);
+      cur = cur.cause;
+    } else {
+      lines.push(String(cur));
+      cur = cur?.cause;
+    }
+  }
+  return lines.length ? lines.join("\n") : void 0;
+}
 function wrapXHR(opts) {
   if (typeof XMLHttpRequest === "undefined") return () => {
   };
@@ -619,6 +664,7 @@ function wrapXHR(opts) {
     }
     s.start = Date.now();
     s.reqBody = typeof body === "string" ? body : void 0;
+    const sendSiteStack = captureCallSiteStack();
     opts.emit({
       phase: "request",
       reqId: s.reqId,
@@ -636,25 +682,32 @@ function wrapXHR(opts) {
         method: s.method,
         url: s.url,
         status: this.status,
+        // XHR exposes statusText directly; same display purpose as fetch.
+        statusText: this.statusText || void 0,
         durationMs: Date.now() - s.start,
         resHeaders: headers,
         resBody
       });
     };
-    const onError = () => {
+    const onError = (kind) => () => {
       opts.emit({
         phase: "error",
         reqId: s.reqId,
         method: s.method,
         url: s.url,
         durationMs: Date.now() - s.start,
-        errorMessage: this.statusText || "xhr error"
+        // Distinguish error/timeout/abort in the message — the standard
+        // XHR `statusText` is empty for `error` and unhelpful for the
+        // others, so we synthesise a clear label.
+        errorMessage: this.statusText || `xhr ${kind}`,
+        errorName: `XHR${kind[0].toUpperCase()}${kind.slice(1)}`,
+        errorStack: sendSiteStack
       });
     };
     this.addEventListener("load", onLoad);
-    this.addEventListener("error", onError);
-    this.addEventListener("timeout", onError);
-    this.addEventListener("abort", onError);
+    this.addEventListener("error", onError("error"));
+    this.addEventListener("timeout", onError("timeout"));
+    this.addEventListener("abort", onError("abort"));
     return origSend.apply(this, [body]);
   };
   return () => {
@@ -663,6 +716,15 @@ function wrapXHR(opts) {
     proto.setRequestHeader = origSetReqHeader;
   };
 }
+function captureCallSiteStack() {
+  try {
+    throw new Error("xhr-callsite");
+  } catch (err) {
+    if (!(err instanceof Error) || !err.stack) return void 0;
+    const lines = err.stack.split("\n");
+    return lines.slice(2).join("\n") || void 0;
+  }
+}
 function parseXhrHeaders(raw) {
   const out = {};
   if (!raw) return out;
@@ -757,6 +819,10 @@ var CommandRegistry = class {
 };
 var MAX_DUMP_BYTES = 64 * 1024;
 var MAX_SCREENSHOT_BYTES = 1024 * 1024;
+var MAX_EXEC_CODE_BYTES = 8 * 1024;
+var DEFAULT_EXEC_TIMEOUT_MS = 5e3;
+var MIN_EXEC_TIMEOUT_MS = 250;
+var MAX_EXEC_TIMEOUT_MS = 3e4;
 async function defaultDomScreenshot() {
   if (typeof document === "undefined" || typeof window === "undefined") {
     throw new Error(
@@ -871,6 +937,9 @@ function registerBuiltins(registry, hooks = {}) {
   registry.register("dump-state", makeDumpState(hooks.getState));
   registry.register("set-feature-flag", makeSetFlag(hooks.setFeatureFlag));
   registry.register("screenshot", makeScreenshot(hooks.screenshot));
+  if (hooks.exec !== false) {
+    registry.register("exec", makeExec(hooks.exec ?? {}));
+  }
 }
 var ping = () => ({ ok: true, ts: Date.now() });
 function makeReload(reload) {
@@ -933,6 +1002,168 @@ function makeScreenshot(screenshot) {
     return { format, data, bytes: data.length };
   };
 }
+var cachedBOT = void 0;
+function getBOT() {
+  if (cachedBOT !== void 0) return cachedBOT;
+  if (typeof window === "undefined") {
+    cachedBOT = null;
+    return null;
+  }
+  try {
+    const w = window;
+    if (w.BOT) {
+      cachedBOT = w.BOT;
+      return cachedBOT;
+    }
+  } catch {
+  }
+  try {
+    const w = window;
+    const ng = w.angular;
+    if (ng?.element && typeof document !== "undefined") {
+      const injector = ng.element(document).injector?.();
+      const bot = injector?.get?.("BOT");
+      if (bot != null) {
+        cachedBOT = bot;
+        return cachedBOT;
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function makeExec(opts) {
+  const extraGlobalNames = Object.keys(opts.globals ?? {});
+  const extraGlobalValues = extraGlobalNames.map((k) => opts.globals[k]);
+  return async (args, ctx) => {
+    if (typeof args.code !== "string" || args.code.length === 0) {
+      throw new Error("args.code (non-empty string) is required");
+    }
+    if (args.code.length > MAX_EXEC_CODE_BYTES) {
+      throw new Error(`args.code ${args.code.length} bytes exceeds limit ${MAX_EXEC_CODE_BYTES}`);
+    }
+    const timeoutMs = clamp(
+      typeof args.timeoutMs === "number" ? args.timeoutMs : DEFAULT_EXEC_TIMEOUT_MS,
+      MIN_EXEC_TIMEOUT_MS,
+      MAX_EXEC_TIMEOUT_MS
+    );
+    const start = Date.now();
+    const logs = [];
+    const consoleMethods = ["log", "info", "warn", "error", "debug"];
+    const originals = {};
+    if (typeof console !== "undefined") {
+      for (const m of consoleMethods) {
+        const orig = console[m];
+        if (typeof orig !== "function") continue;
+        originals[m] = orig;
+        const captured = (...callArgs) => {
+          logs.push({ method: m, args: callArgs.map(execSafeClone), ts: Date.now() });
+          try {
+            orig.call(console, ...callArgs);
+          } catch {
+          }
+        };
+        console[m] = captured;
+      }
+    }
+    let value;
+    let threw = void 0;
+    try {
+      const AsyncFunction = Object.getPrototypeOf(async function() {
+      }).constructor;
+      const localNames = ["BOT", "window", "document", ...extraGlobalNames];
+      const localValues = [
+        getBOT(),
+        typeof window !== "undefined" ? window : void 0,
+        typeof document !== "undefined" ? document : void 0,
+        ...extraGlobalValues
+      ];
+      let fnTry = null;
+      try {
+        fnTry = new AsyncFunction(...localNames, `return (${args.code});`);
+      } catch (e) {
+        if (!(e instanceof SyntaxError)) throw e;
+      }
+      const fn = fnTry ?? new AsyncFunction(...localNames, args.code);
+      let timer = null;
+      let abortReject = null;
+      const onAbort = () => abortReject?.(new Error("exec cancelled"));
+      ctx.signal?.addEventListener?.("abort", onAbort);
+      try {
+        value = await Promise.race([
+          fn(...localValues),
+          new Promise((_, reject) => {
+            timer = setTimeout(
+              () => reject(new Error(`exec exceeded ${timeoutMs}ms`)),
+              timeoutMs
+            );
+          }),
+          new Promise((_, reject) => {
+            abortReject = reject;
+          })
+        ]);
+      } finally {
+        if (timer) clearTimeout(timer);
+        ctx.signal?.removeEventListener?.("abort", onAbort);
+      }
+    } catch (err) {
+      threw = err;
+    } finally {
+      if (typeof console !== "undefined") {
+        for (const m of consoleMethods) {
+          if (originals[m]) {
+            console[m] = originals[m];
+          }
+        }
+      }
+    }
+    if (threw !== void 0) {
+      const e = threw instanceof Error ? threw : new Error(String(threw));
+      const stackTruncated = typeof e.stack === "string" ? e.stack.split("\n").slice(0, 20).join("\n") : void 0;
+      const detail = {
+        name: e.name,
+        message: e.message,
+        stack: stackTruncated,
+        logs,
+        durationMs: Date.now() - start
+      };
+      const wrapped = new Error(JSON.stringify(detail));
+      wrapped.detail = detail;
+      throw wrapped;
+    }
+    return {
+      ok: true,
+      value: execSafeClone(value),
+      logs,
+      durationMs: Date.now() - start
+    };
+  };
+}
+function clamp(n, lo, hi) {
+  if (!Number.isFinite(n)) return lo;
+  return Math.min(Math.max(n, lo), hi);
+}
+function execSafeClone(v) {
+  try {
+    return JSON.parse(JSON.stringify(v, (_k, val) => {
+      if (typeof val === "function") {
+        return `[Function: ${val.name || "anonymous"}]`;
+      }
+      if (val instanceof Error) {
+        return { name: val.name, message: val.message, stack: val.stack };
+      }
+      if (typeof val === "bigint") return val.toString() + "n";
+      if (typeof val === "undefined") return null;
+      if (val && typeof val === "object" && val.nodeType === 1) {
+        const el = val;
+        return `[${el.tagName ?? "Element"}${el.id ? "#" + el.id : ""}]`;
+      }
+      return val;
+    }));
+  } catch {
+    return { __unserializable: typeof v };
+  }
+}
 function safeStringify(v) {
   try {
     const seen = /* @__PURE__ */ new WeakSet();
@@ -1380,5 +1611,6 @@ exports.DEFAULT_MAX_BODY_BYTES = DEFAULT_MAX_BODY_BYTES;
 exports.DEFAULT_REDACT_HEADERS = DEFAULT_REDACT_HEADERS;
 exports.SCHEMA_VERSION = SCHEMA_VERSION;
 exports.enableRemoteDebug = enableRemoteDebug;
+exports.getBOT = getBOT;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map