@farmslot/adapter-rn 0.15.0 → 0.17.0

package/bridge-runtime/lib/cdp-eval.cjs

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * Evaluate a JS expression in the app's Hermes runtime via CDP Runtime.evaluate.
+ * Returns the evaluated value (primitives and JSON-serialisable objects).
+ */
+async function cdpEval(client, expression) {
+  // Hermes doesn't support async in Runtime.evaluate, use a plain IIFE
+  const wrapped = `(function() { return (${expression}); })()`;
+  const result = await client.send('Runtime.evaluate', {
+    expression: wrapped,
+    returnByValue: true,
+    awaitPromise: false,
+    generatePreview: false,
+  });
+
+  if (result.exceptionDetails) {
+    const desc =
+      result.exceptionDetails.exception?.description ||
+      result.exceptionDetails.text ||
+      JSON.stringify(result.exceptionDetails);
+    throw new Error(`Evaluation error: ${desc}`);
+  }
+
+  return result.result?.value;
+}
+
+/**
+ * Evaluate a JS expression that returns a Promise.
+ * Hermes CDP doesn't support awaitPromise, so we store the result on
+ * globalThis.__cdp_async__ and poll for it.
+ */
+async function cdpEvalAsync(client, expression, timeoutMs = cdpMessageTimeout()) {
+  // Unique key per call to avoid collisions
+  const key = `__cdp_async_${Date.now()}_${Math.random().toString(36).slice(2)}__`;
+
+  // Kick off the promise, store result when done.
+  // The try/catch guards against synchronous throws during argument evaluation
+  // of Promise.resolve(<expression>) — without it, a sync error escapes the
+  // IIFE and globalThis[key] stays 'pending' forever.
+  const kickoff = `(function() {
+    globalThis['${key}'] = { status: 'pending' };
+    try {
+      Promise.resolve(${expression})
+        .then(function(v) { globalThis['${key}'] = { status: 'resolved', value: v }; })
+        .catch(function(e) { globalThis['${key}'] = { status: 'rejected', error: String(e) }; });
+    } catch(e) {
+      globalThis['${key}'] = { status: 'rejected', error: String(e) };
+    }
+    return 'started';
+  })()`;
+
+  const kickoffResult = await client.send(
+    'Runtime.evaluate',
+    {
+      expression: kickoff,
+      returnByValue: true,
+      awaitPromise: false,
+    },
+    timeoutMs,
+  );
+
+  // If the IIFE itself failed to evaluate (syntax error, etc.), bail early
+  if (kickoffResult.exceptionDetails) {
+    const desc =
+      kickoffResult.exceptionDetails.exception?.description ||
+      kickoffResult.exceptionDetails.text ||
+      JSON.stringify(kickoffResult.exceptionDetails);
+    throw new Error(`Async evaluation error: ${desc}`);
+  }
+
+  // Best-effort cleanup — swallow errors so a disconnected WebSocket
+  // doesn't obscure the actual result or diagnostic error.
+  const cleanup = () =>
+    client
+      .send('Runtime.evaluate', {
+        expression: `delete globalThis['${key}']`,
+        returnByValue: true,
+        awaitPromise: false,
+      })
+
+      .catch(() => {});
+
+  // Poll for completion
+  const pollInterval = 200;
+  const deadline = Date.now() + timeoutMs;
+  try {
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, pollInterval));
+      const check = await client.send(
+        'Runtime.evaluate',
+        {
+          expression: `(function() { return globalThis['${key}']; })()`,
+          returnByValue: true,
+          awaitPromise: false,
+        },
+        timeoutMs,
+      );
+      const val = check.result?.value;
+      if (val?.status === 'resolved') {
+        return val.value;
+      }
+      if (val?.status === 'rejected') {
+        throw new Error(`Async evaluation error: ${val.error}`);
+      }
+    }
+    throw new Error(`Async evaluation timed out after ${timeoutMs}ms`);
+  } finally {
+    await cleanup();
+  }
+}
+
+function cdpMessageTimeout() {
+  const timeoutMs = Number.parseInt(process.env.CDP_TIMEOUT || '30000', 10);
+  return Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 30000;
+}
+
+module.exports = { cdpEval, cdpEvalAsync };

package/bridge-runtime/lib/config.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** Read a value from .js.env */
+function loadEnvValue(key, appRoot = process.env.APP_ROOT || process.cwd()) {
+  try {
+    const envPath = path.resolve(appRoot, '.js.env');
+    const content = fs.readFileSync(envPath, 'utf8');
+    // .js.env uses `export KEY="value"` (shell-sourceable format),
+    // so we handle the optional `export` prefix and strip surrounding quotes.
+    const match = content.match(new RegExp(String.raw`^(?:export\s+)?${key}=(.+)$`, 'm'));
+    if (match) return match[1].trim().replace(/^["']/, '').replace(/["']$/, '');
+  } catch {
+    // .js.env may not exist — fall through to undefined
+  }
+  return undefined;
+}
+
+function resolvePort(env = process.env, appRoot = env.APP_ROOT || process.cwd()) {
+  return (
+    env.WATCHER_PORT ||
+    env.METRO_PORT ||
+    loadEnvValue('WATCHER_PORT', appRoot) ||
+    loadEnvValue('METRO_PORT', appRoot) ||
+    '8081'
+  );
+}
+
+/** Read WATCHER_PORT from .js.env or env (default: 8081) */
+function loadPort() {
+  return Number.parseInt(resolvePort(), 10);
+}
+
+/** Read IOS_SIMULATOR name from .js.env or env (default: none — accept any device) */
+function loadSimulatorName() {
+  // Explicit empty string in env means "no simulator" — don't fall through to .js.env
+  if ('IOS_SIMULATOR' in process.env) return process.env.IOS_SIMULATOR;
+  return loadEnvValue('IOS_SIMULATOR') || '';
+}
+
+/** Read ANDROID_DEVICE from .js.env or env (default: none — accept any device) */
+function loadAndroidDevice() {
+  if ('ANDROID_DEVICE' in process.env) return process.env.ANDROID_DEVICE;
+  return loadEnvValue('ANDROID_DEVICE') || '';
+}
+
+/**
+ * Read ANDROID_TARGET_DEVICE_NAME from env — the Metro-compatible model prefix
+ * resolved from an adb serial by bridge.mjs. Used by target-discovery to select
+ * the correct Metro CDP target when multiple devices are connected.
+ *
+ * Set automatically by the bridge when --device <serial> is used. Users never
+ * need to set this; pass --device <adb-serial> and the harness maps it internally.
+ */
+function loadAndroidTargetDeviceName() {
+  return process.env.ANDROID_TARGET_DEVICE_NAME || '';
+}
+
+module.exports = {
+  loadEnvValue,
+  loadPort,
+  resolvePort,
+  loadSimulatorName,
+  loadAndroidDevice,
+  loadAndroidTargetDeviceName,
+};

package/bridge-runtime/lib/console-format.cjs

@@ -0,0 +1,54 @@
+'use strict';
+
+// Render CDP Runtime.consoleAPICalled args (RemoteObjects) into a log line.
+// Primitives carry `value`; objects/arrays do not — a bare console.log(obj)
+// arrived as the literal "Object". Hermes ships an inline `preview` (the same
+// one React Native DevTools renders in its console), so objects expand from it
+// synchronously — no extra CDP round-trip, so the stream never blocks. Depth is
+// bounded because previews nest one level via `valuePreview`; beyond that the
+// child preview's own description is used.
+
+const MAX_PREVIEW_DEPTH = 2;
+
+function formatPropertyValue(prop, depth) {
+  if (prop.valuePreview && depth < MAX_PREVIEW_DEPTH) {
+    return formatPreview(prop.valuePreview, depth + 1);
+  }
+  if (prop.type === 'string' && prop.value !== undefined) return JSON.stringify(prop.value);
+  if (prop.value !== undefined) return String(prop.value);
+  return prop.subtype || prop.type || '';
+}
+
+function formatPreview(preview, depth) {
+  const properties = Array.isArray(preview.properties) ? preview.properties : [];
+  const overflow = preview.overflow ? ', …' : '';
+  if (preview.subtype === 'array') {
+    return `[${properties.map((p) => formatPropertyValue(p, depth)).join(', ')}${overflow}]`;
+  }
+  const body = properties.map((p) => `${p.name}: ${formatPropertyValue(p, depth)}`).join(', ');
+  // Name a non-plain constructor (Error, Map, custom class) so the class is not lost.
+  const ctor =
+    preview.description && preview.description !== 'Object' ? `${preview.description} ` : '';
+  return properties.length > 0 || overflow ? `${ctor}{ ${body}${overflow} }` : `${ctor}{}`;
+}
+
+function formatRemoteObject(a) {
+  if (!a || typeof a !== 'object') return String(a == null ? '' : a);
+  // Primitives (number/boolean/string) carry a directly-usable value.
+  if (a.type !== 'object' && a.type !== 'function' && a.value !== undefined) return String(a.value);
+  if (a.type === 'undefined') return 'undefined';
+  if (a.subtype === 'null') return 'null';
+  if (a.preview) return formatPreview(a.preview, 1);
+  // Functions, errors, and objects with no preview: the description is the best
+  // available text (className / Error stack / etc.); fall back to bare value/type.
+  if (a.description !== undefined) return a.description;
+  if (a.value !== undefined) return String(a.value);
+  return a.type || '';
+}
+
+function formatArgs(args, maxLineChars) {
+  const text = (args || []).map(formatRemoteObject).join(' ');
+  return maxLineChars && text.length > maxLineChars ? `${text.slice(0, maxLineChars)}…` : text;
+}
+
+module.exports = { formatArgs, formatRemoteObject, formatPreview };

package/bridge-runtime/lib/devtools-proxy.cjs

@@ -0,0 +1,169 @@
+'use strict';
+
+const fs = require('node:fs');
+const { WebSocket, WebSocketServer } = require('ws');
+
+const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+const SESSION_TIMEOUT_MS = 10_000;
+const EVENT_GATED_DOMAINS = new Set([
+  'Debugger',
+  'Log',
+  'Network',
+  'Page',
+  'ReactNativeApplication',
+  'Runtime',
+]);
+
+function createDevtoolsProxy({
+  descriptorPath,
+  sessions,
+  sendCommand,
+  requestDiscovery,
+  allowedOrigins,
+}) {
+  if (!Array.isArray(allowedOrigins) || allowedOrigins.length === 0) {
+    throw new Error('DevTools proxy requires at least one allowed Origin');
+  }
+  let listeningPort = null;
+  const clients = new Set();
+  const server = new WebSocketServer({
+    host: '127.0.0.1',
+    port: 0,
+    maxPayload: MAX_FRAME_BYTES,
+  });
+
+  async function waitForSession(deviceId) {
+    const ready = sessions.get(deviceId);
+    if (ready?.brokerReady) return ready;
+    requestDiscovery();
+    const deadline = Date.now() + SESSION_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      const session = sessions.get(deviceId);
+      if (session?.brokerReady) return session;
+    }
+    throw new Error('Hermes runtime is unavailable or reloading; retry the command');
+  }
+
+  function writeDescriptor() {
+    if (!listeningPort) return;
+    fs.writeFileSync(
+      descriptorPath,
+      `${JSON.stringify({ schemaVersion: 1, pid: process.pid, port: listeningPort })}\n`,
+      { mode: 0o600 },
+    );
+  }
+
+  async function forward(client, message) {
+    if (
+      !message ||
+      typeof message !== 'object' ||
+      !Number.isInteger(message.id) ||
+      typeof message.method !== 'string'
+    ) {
+      return;
+    }
+    if (message.method.endsWith('.disable')) {
+      client.enabled.delete(message.method.replace(/\.disable$/u, '.enable'));
+      if (client.socket.readyState === WebSocket.OPEN) {
+        client.socket.send(JSON.stringify({ id: message.id, result: {} }));
+      }
+      return;
+    }
+    const isEnable = message.method.endsWith('.enable');
+    if (isEnable) {
+      client.enabled.set(message.method, message.params || {});
+    }
+    try {
+      const session = await waitForSession(client.deviceId);
+      const result = await sendCommand(
+        session,
+        message.method,
+        message.params || {},
+        SESSION_TIMEOUT_MS,
+      );
+      if (client.socket.readyState === WebSocket.OPEN) {
+        client.socket.send(JSON.stringify({ id: message.id, result }));
+      }
+    } catch (error) {
+      if (isEnable) client.enabled.delete(message.method);
+      if (client.socket.readyState === WebSocket.OPEN) {
+        client.socket.send(
+          JSON.stringify({
+            id: message.id,
+            error: {
+              code: -32000,
+              message: String(error?.message || error).slice(0, 256),
+            },
+          }),
+        );
+      }
+    }
+  }
+
+  server.on('connection', (socket, request) => {
+    const url = new URL(request.url || '/', 'http://127.0.0.1');
+    const deviceId = url.searchParams.get('device');
+    if (!deviceId || !allowedOrigins.includes(request.headers.origin)) {
+      socket.close(1008, 'invalid DevTools proxy Origin or device');
+      return;
+    }
+    for (const client of clients) {
+      if (client.deviceId === deviceId) {
+        client.socket.close(1000, 'replaced by a newer DevTools window');
+      }
+    }
+    const client = { socket, deviceId, enabled: new Map() };
+    clients.add(client);
+    socket.on('message', (data) => {
+      let message;
+      try {
+        message = JSON.parse(String(data));
+      } catch {
+        return;
+      }
+      void forward(client, message);
+    });
+    const drop = () => clients.delete(client);
+    socket.on('close', drop);
+    socket.on('error', drop);
+  });
+
+  server.on('listening', () => {
+    const address = server.address();
+    if (!address || typeof address === 'string') return;
+    listeningPort = address.port;
+    writeDescriptor();
+  });
+
+  return {
+    onSessionOpen(deviceId, session) {
+      for (const client of clients) {
+        if (client.deviceId !== deviceId) continue;
+        for (const [method, params] of client.enabled) {
+          void sendCommand(session, method, params, SESSION_TIMEOUT_MS).catch(() => undefined);
+        }
+      }
+    },
+    onCdpEvent(deviceId, method, params) {
+      const payload = JSON.stringify({ method, params });
+      const domain = method.split('.', 1)[0];
+      for (const client of clients) {
+        if (
+          client.deviceId === deviceId &&
+          client.socket.readyState === WebSocket.OPEN &&
+          (!EVENT_GATED_DOMAINS.has(domain) || client.enabled.has(`${domain}.enable`))
+        ) {
+          client.socket.send(payload);
+        }
+      }
+    },
+    close() {
+      for (const client of clients) client.socket.close();
+      server.close();
+      fs.rmSync(descriptorPath, { force: true });
+    },
+  };
+}
+
+module.exports = { createDevtoolsProxy };

package/bridge-runtime/lib/issue-capture.cjs

@@ -0,0 +1,86 @@
+'use strict';
+
+// In-app issue buffer for a React Native (Hermes) runtime: the arm snippet hooks
+// console.warn/error, global errors and unhandled rejections into a bounded
+// buffer; the collect snippet drains it. Callers evaluate both over CDP.
+
+// Installed into the Hermes runtime via Runtime.evaluate. Returns a string
+// so callers can embed it directly into eval expressions. Keeps the hook
+// idempotent and bounded (500-entry cap).
+function buildArmSnippet() {
+  return `(() => {
+  var g = globalThis;
+  if (g.__AGENTIC_ISSUES_INSTALLED__) { return { installed: true, reason: 'already-installed' }; }
+  g.__AGENTIC_ISSUES__ = [];
+  g.__AGENTIC_ISSUES_CAP__ = 500;
+  var push = function (entry) {
+    try {
+      if (g.__AGENTIC_ISSUES__.length < g.__AGENTIC_ISSUES_CAP__) {
+        g.__AGENTIC_ISSUES__.push(entry);
+      }
+    } catch (_e) {}
+  };
+  ['warn', 'error'].forEach(function (k) {
+    var orig = console[k] && console[k].bind(console);
+    if (!orig) return;
+    console[k] = function () {
+      var args = Array.prototype.slice.call(arguments);
+      try {
+        var text = args.map(function (a) {
+          if (a && a.stack) return String(a.stack);
+          if (typeof a === 'string') return a;
+          try { return JSON.stringify(a); } catch (_e) { return String(a); }
+        }).join(' ');
+        push({ t: Date.now(), level: k, text: text });
+      } catch (_e) {}
+      return orig.apply(console, args);
+    };
+  });
+  if (typeof g.addEventListener === 'function') {
+    try {
+      g.addEventListener('error', function (e) {
+        var err = e && (e.error || e.message);
+        var text = err && err.stack ? err.stack : String(err || e);
+        push({ t: Date.now(), level: 'exception', text: text });
+      });
+      g.addEventListener('unhandledrejection', function (e) {
+        var r = e && e.reason;
+        var text = r && r.stack ? r.stack : String(r || e);
+        push({ t: Date.now(), level: 'exception', text: text });
+      });
+    } catch (_e) {}
+  }
+  var ep = g.ErrorUtils;
+  if (ep && typeof ep.setGlobalHandler === 'function') {
+    try {
+      var priorHandler = typeof ep.getGlobalHandler === 'function' ? ep.getGlobalHandler() : null;
+      ep.setGlobalHandler(function (err, isFatal) {
+        try {
+          var text = err && err.stack ? err.stack : String(err);
+          push({ t: Date.now(), level: 'exception', text: (isFatal ? '[FATAL] ' : '') + text });
+        } catch (_e) {}
+        if (typeof priorHandler === 'function') {
+          try { priorHandler(err, isFatal); } catch (_e) {}
+        }
+      });
+    } catch (_e) {}
+  }
+  g.__AGENTIC_ISSUES_INSTALLED__ = true;
+  return { installed: true };
+})()`;
+}
+
+function buildCollectSnippet() {
+  return `(() => {
+  var g = globalThis;
+  var buf = g.__AGENTIC_ISSUES__ || [];
+  var snapshot = buf.slice();
+  g.__AGENTIC_ISSUES__ = [];
+  return { count: snapshot.length, entries: snapshot };
+})()`;
+}
+
+module.exports = {
+  buildArmSnippet,
+  buildCollectSnippet,
+};

package/bridge-runtime/lib/match-bridge-target.cjs

@@ -0,0 +1,89 @@
+'use strict';
+
+// Boundary-safe matcher for CDP bridge targets, shared by wait-for-bridge and the
+// launch ready-path confirm. A launch (or its confirm) may only accept a target
+// belonging to the REQUESTED platform — and the requested device when one is pinned.
+//
+// The requested platform is authoritative and is passed explicitly
+// (WAIT_FOR_BRIDGE_PLATFORM), so it wins over env inference. On a dual-platform slot
+// the other platform's device identity is ambiently injected (a slot-context
+// IOS_SIMULATOR while launching android, or vice versa); without an explicit platform
+// the matcher would fall back to that ambient identity and confirm against the wrong
+// platform's target. Binding the platform up front closes that corner.
+
+function matchesBridgeTarget(target, env) {
+  const e = env || process.env;
+  if (!target || typeof target !== 'object') return false;
+
+  const requirePlatform = e.WAIT_FOR_BRIDGE_PLATFORM || '';
+  // Requested platform is authoritative: never accept the other platform's target,
+  // whatever device env is ambiently present.
+  if (requirePlatform && target.platform !== requirePlatform) return false;
+
+  const androidName = e.ANDROID_TARGET_DEVICE_NAME || e.ANDROID_DEVICE || '';
+  const adbSerial = e.ADB_SERIAL || e.ANDROID_SERIAL || '';
+  const iosSimulator = e.IOS_SIMULATOR || '';
+
+  // Android device pin applies only when android is requested (or nothing constrains
+  // the platform); it must never redirect a platform-bound iOS confirm — a slot-context
+  // ADB_SERIAL while launching iOS must not reject every iOS target. Symmetric with the
+  // iOS-simulator branch below.
+  if ((adbSerial || androidName) && (!requirePlatform || requirePlatform === 'android')) {
+    // Require android + boundary-safe device-name match.
+    if (target.platform !== 'android') return false;
+    if (!androidName) return true;
+    const deviceName = String(target.deviceName || '');
+    return deviceName === androidName || deviceName.startsWith(`${androidName} -`);
+  }
+
+  // iOS simulator pin applies only when iOS is requested (or nothing constrains the
+  // platform); it must never redirect a platform-bound android confirm.
+  if (iosSimulator && (!requirePlatform || requirePlatform === 'ios')) {
+    return target.platform !== 'android' && target.deviceName === iosSimulator;
+  }
+
+  // No device pin: the platform gate above is the only constraint.
+  return true;
+}
+
+// True when at least one answering target matches the request AND carries a route
+// (an in-app agentic bridge is live), not merely a registered debug target.
+function hasMatchingRoute(value, env) {
+  const targets = Array.isArray(value) ? value : [value];
+  return targets.some(
+    (t) => matchesBridgeTarget(t, env) && t && t.agenticPresent === true && Boolean(t.route),
+  );
+}
+
+// Human summary of the targets that answered (platform / deviceName), for teaching on
+// a timeout — e.g. an iOS target answering an android launch.
+function describeTargets(value) {
+  const targets = (Array.isArray(value) ? value : [value]).filter(
+    (t) => t && typeof t === 'object',
+  );
+  if (!targets.length) return 'none';
+  return targets
+    .map(
+      (t) =>
+        `${t.platform || '?'}${t.deviceName ? `/'${t.deviceName}'` : ''}${t.route ? '' : ' (no route)'}`,
+    )
+    .join(', ');
+}
+
+// Human summary of what the run is pinned to, for the same teaching line.
+function describeRequested(env) {
+  const e = env || process.env;
+  const platform = e.WAIT_FOR_BRIDGE_PLATFORM || '';
+  const androidName = e.ANDROID_TARGET_DEVICE_NAME || e.ANDROID_DEVICE || '';
+  const adbSerial = e.ADB_SERIAL || e.ANDROID_SERIAL || '';
+  const iosSimulator = e.IOS_SIMULATOR || '';
+  // Explicit requested platform wins over device-env inference: an iOS-bound confirm
+  // with an ambient ADB_SERIAL is still iOS.
+  if (platform === 'android') return `android${androidName ? ` / ${androidName}` : ''}`;
+  if (platform === 'ios') return `ios${iosSimulator ? ` / ${iosSimulator}` : ''}`;
+  if (adbSerial || androidName) return `android${androidName ? ` / ${androidName}` : ''}`;
+  if (iosSimulator) return `ios${iosSimulator ? ` / ${iosSimulator}` : ''}`;
+  return 'any platform';
+}
+
+module.exports = { matchesBridgeTarget, hasMatchingRoute, describeTargets, describeRequested };