@botim/mp-debug-sdk 0.5.2 → 0.6.2

package/README.md

@@ -8,15 +8,20 @@ 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
 
+> **Heads-up — registry override required in BOTIM repos.**
+> Most BOTIM mini-program repos pin the `@botim` scope to the internal Artifactory mirror (`@botim:registry=https://artifactory.corp.algento.com/artifactory/api/npm/bot-npm/`). This SDK is **published to public npm**, so a plain `npm install @botim/mp-debug-sdk` in those repos will hit Artifactory, not find the package, and 404. Use the public registry explicitly for this one package:
+
 ```bash
-npm install @botim/mp-debug-sdk
+npm install @botim/mp-debug-sdk --registry=https://registry.npmjs.org/
 ```
 
+If your repo doesn't have an `@botim` scope override (rare), the flag is harmless — npm uses `registry.npmjs.org` by default. **Don't** add `@botim:registry=https://registry.npmjs.org/` to your `.npmrc`: it would shadow the internal Artifactory registry that other `@botim/*` packages (mp-framework, etc.) need.
+
 ## 1. Add the env config files
 
 Each environment of your mini-program ships with one config file at the project root, in the standard BOTIM mini-program schema:
@@ -128,7 +133,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 +203,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
@@ -186,6 +242,16 @@ Once your build is wired and shipped, see **[`docs/live-debugging.md`](./docs/li
 | `RemoteDebugHandle.flush()` | Force-flush the in-memory buffer. |
 | `RemoteDebugHandle.stop()` | Uninstall and drain the queue. |
 
+## AI debug skill (Claude Code)
+
+A Claude Code skill that teaches AI agents how to wire and consume this SDK lives at `.claude/skills/botim-debug-relay/SKILL.md`. Open Claude Code from this repo and the skill auto-loads — no setup needed. To use it from anywhere on your machine:
+
+```bash
+cp -r .claude/skills/botim-debug-relay ~/.claude/skills/
+```
+
+> **The file in this repo is a mirror.** The canonical copy lives in `botim-debug-relay/.claude/skills/botim-debug-relay/SKILL.md`. **Do not edit the SDK-side copy directly** — your changes will be overwritten by the next sync. Edit in the relay repo, then run `bash bin/sync-skill.sh` from that repo to propagate here.
+
 ## License
 
 [ISC](./LICENSE) © BOTIM

package/dist/index.cjs

@@ -819,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(
@@ -933,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) {
@@ -995,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();
@@ -1442,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