agent-react-devtools 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# agent-react-devtools
+
+## 0.1.0
+
+### Minor Changes
+
+- d1e02f9: **Daemon, DevTools bridge, and component tree**
+
+  **Daemon** — Persistent background process with IPC server (Unix socket) that manages connections and dispatches commands.
+
+  **DevTools Bridge** — WebSocket server implementing the React DevTools "Wall" protocol. Connects to running React apps via `react-devtools-core`.
+
+  **Component Tree** — Parse and inspect the full React component hierarchy:
+
+  - View component tree with types, keys, and parent/child relationships
+  - Inspect props, state, and hooks of any component
+  - Search components by display name (fuzzy or exact match)
+  - Count components by type
+
+  **CLI** — Command-line interface with commands: `start`, `stop`, `status`, `tree`, `find`, `count`, `get component`.
+
+  **Formatting** — Token-efficient output designed for LLM consumption.
+
+- 626a21a: **Profiler**
+
+  Start and stop profiling sessions to capture render performance data from connected React apps.
+
+  - **Render reports** — Per-component render duration and count
+  - **Slowest components** — Ranked by self render time
+  - **Most re-rendered** — Ranked by render count
+  - **Commit timeline** — Chronological view of React commits with durations
+  - **Commit details** — Per-component breakdown for a specific commit, sorted by self time
+
+  CLI commands: `profile start`, `profile stop`, `profile report`, `profile slow`, `profile rerenders`, `profile timeline`, `profile commit`.

package/dist/cli.js

@@ -0,0 +1,584 @@
+#!/usr/bin/env node
+
+// src/daemon-client.ts
+import net from "net";
+import fs from "fs";
+import path from "path";
+import { spawn } from "child_process";
+var DEFAULT_STATE_DIR = path.join(
+  process.env.HOME || process.env.USERPROFILE || "/tmp",
+  ".agent-react-devtools"
+);
+var stateDir = DEFAULT_STATE_DIR;
+function setStateDir(dir) {
+  stateDir = dir;
+}
+function getDaemonInfoPath() {
+  return path.join(stateDir, "daemon.json");
+}
+function getSocketPath() {
+  return path.join(stateDir, "daemon.sock");
+}
+function readDaemonInfo() {
+  try {
+    const raw = fs.readFileSync(getDaemonInfoPath(), "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function isDaemonAlive(info) {
+  try {
+    process.kill(info.pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function ensureDaemon(port) {
+  const info = readDaemonInfo();
+  if (info && isDaemonAlive(info)) {
+    return;
+  }
+  try {
+    fs.unlinkSync(getDaemonInfoPath());
+  } catch {
+  }
+  try {
+    fs.unlinkSync(getSocketPath());
+  } catch {
+  }
+  const daemonScript = path.join(
+    path.dirname(new URL(import.meta.url).pathname),
+    "daemon.js"
+  );
+  const args = [];
+  if (port) args.push(`--port=${port}`);
+  if (stateDir !== DEFAULT_STATE_DIR) args.push(`--state-dir=${stateDir}`);
+  const child = spawn(process.execPath, [daemonScript, ...args], {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+  const deadline = Date.now() + 5e3;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 100));
+    try {
+      await sendCommand({ type: "ping" });
+      return;
+    } catch {
+    }
+  }
+  throw new Error("Daemon failed to start within 5 seconds");
+}
+function stopDaemon() {
+  const info = readDaemonInfo();
+  if (!info) return false;
+  try {
+    process.kill(info.pid, "SIGTERM");
+    try {
+      fs.unlinkSync(getDaemonInfoPath());
+    } catch {
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function sendCommand(cmd) {
+  return new Promise((resolve, reject) => {
+    const socketPath = getSocketPath();
+    const conn = net.createConnection(socketPath, () => {
+      conn.write(JSON.stringify(cmd) + "\n");
+    });
+    let buffer = "";
+    conn.on("data", (chunk) => {
+      buffer += chunk.toString();
+      const newlineIdx = buffer.indexOf("\n");
+      if (newlineIdx !== -1) {
+        const line = buffer.slice(0, newlineIdx);
+        conn.end();
+        try {
+          resolve(JSON.parse(line));
+        } catch {
+          reject(new Error("Invalid response from daemon"));
+        }
+      }
+    });
+    conn.on("error", (err) => {
+      reject(new Error(`Cannot connect to daemon: ${err.message}`));
+    });
+    conn.setTimeout(3e4, () => {
+      conn.destroy();
+      reject(new Error("Command timed out"));
+    });
+  });
+}
+
+// src/formatters.ts
+var TYPE_ABBREV = {
+  function: "fn",
+  class: "cls",
+  host: "host",
+  memo: "memo",
+  forwardRef: "fRef",
+  profiler: "prof",
+  suspense: "susp",
+  context: "ctx",
+  other: "?"
+};
+function typeTag(type) {
+  return TYPE_ABBREV[type] || type;
+}
+var PIPE = "\u2502  ";
+var TEE = "\u251C\u2500 ";
+var ELBOW = "\u2514\u2500 ";
+var SPACE = "   ";
+function formatTree(nodes) {
+  if (nodes.length === 0) return "No components (is a React app connected?)";
+  const childrenMap = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    const parentId = node.parentId;
+    let siblings = childrenMap.get(parentId);
+    if (!siblings) {
+      siblings = [];
+      childrenMap.set(parentId, siblings);
+    }
+    siblings.push(node);
+  }
+  const lines = [];
+  function walk(nodeId, prefix, isLast, isRoot) {
+    const node = nodes.find((n) => n.id === nodeId);
+    if (!node) return;
+    const connector = isRoot ? "" : isLast ? ELBOW : TEE;
+    let line = `${node.label} [${typeTag(node.type)}] "${node.displayName}"`;
+    if (node.key) line += ` key="${node.key}"`;
+    lines.push(`${prefix}${connector}${line}`);
+    const children = childrenMap.get(node.id) || [];
+    const childPrefix = isRoot ? "" : prefix + (isLast ? SPACE : PIPE);
+    for (let i = 0; i < children.length; i++) {
+      walk(children[i].id, childPrefix, i === children.length - 1, false);
+    }
+  }
+  const roots = childrenMap.get(null) || [];
+  for (let i = 0; i < roots.length; i++) {
+    walk(roots[i].id, "", i === roots.length - 1, true);
+  }
+  return lines.join("\n");
+}
+function formatComponent(element, label) {
+  const lines = [];
+  const ref = label || `#${element.id}`;
+  let header = `${ref} [${typeTag(element.type)}] "${element.displayName}"`;
+  if (element.key) header += ` key="${element.key}"`;
+  lines.push(header);
+  if (element.props && Object.keys(element.props).length > 0) {
+    lines.push("props:");
+    for (const [key, value] of Object.entries(element.props)) {
+      lines.push(`  ${key}: ${formatCompactValue(value) ?? "undefined"}`);
+    }
+  }
+  if (element.state && Object.keys(element.state).length > 0) {
+    lines.push("state:");
+    for (const [key, value] of Object.entries(element.state)) {
+      lines.push(`  ${key}: ${formatCompactValue(value) ?? "undefined"}`);
+    }
+  }
+  if (element.hooks && element.hooks.length > 0) {
+    lines.push("hooks:");
+    for (const h of element.hooks) {
+      const val = formatCompactValue(h.value);
+      lines.push(val !== void 0 ? `  ${h.name}: ${val}` : `  ${h.name}`);
+      if (h.subHooks && h.subHooks.length > 0) {
+        for (const sh of h.subHooks) {
+          const sval = formatCompactValue(sh.value);
+          lines.push(sval !== void 0 ? `    ${sh.name}: ${sval}` : `    ${sh.name}`);
+        }
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function formatSearchResults(results) {
+  if (results.length === 0) return "No components found";
+  return results.map((n) => {
+    let line = `${n.label} [${typeTag(n.type)}] "${n.displayName}"`;
+    if (n.key) line += ` key="${n.key}"`;
+    return line;
+  }).join("\n");
+}
+function formatCount(counts) {
+  const total = Object.values(counts).reduce((a, b) => a + b, 0);
+  const parts = Object.entries(counts).sort((a, b) => b[1] - a[1]).map(([type, count]) => `${typeTag(type)}:${count}`).join(" ");
+  return `${total} components (${parts})`;
+}
+function formatStatus(status) {
+  const lines = [];
+  lines.push(`Daemon: running (port ${status.port})`);
+  lines.push(
+    `Apps: ${status.connectedApps} connected, ${status.componentCount} components`
+  );
+  if (status.profilingActive) {
+    lines.push("Profiling: active");
+  }
+  const upSec = Math.round(status.uptime / 1e3);
+  lines.push(`Uptime: ${upSec}s`);
+  return lines.join("\n");
+}
+function formatProfileSummary(summary) {
+  const lines = [];
+  const durSec = (summary.duration / 1e3).toFixed(1);
+  lines.push(
+    `Profile "${summary.name}" (${durSec}s, ${summary.commitCount} commits)`
+  );
+  if (summary.componentRenderCounts.length > 0) {
+    lines.push("");
+    lines.push("Top renders:");
+    for (const c of summary.componentRenderCounts.slice(0, 10)) {
+      const name = c.displayName || `#${c.id}`;
+      lines.push(`  ${name}  ${c.count} renders`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatProfileReport(report, label) {
+  const lines = [];
+  const ref = label || `#${report.id}`;
+  lines.push(`${ref} "${report.displayName}"`);
+  lines.push(
+    `renders:${report.renderCount}  avg:${report.avgDuration.toFixed(1)}ms  max:${report.maxDuration.toFixed(1)}ms  total:${report.totalDuration.toFixed(1)}ms`
+  );
+  if (report.causes.length > 0) {
+    lines.push(`causes: ${report.causes.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+function formatSlowest(reports) {
+  if (reports.length === 0) return "No profiling data";
+  const lines = ["Slowest (by avg render time):"];
+  for (const r of reports) {
+    const cause = r.causes[0] || "?";
+    lines.push(
+      `  ${pad(r.displayName, 20)} avg:${r.avgDuration.toFixed(1)}ms  max:${r.maxDuration.toFixed(1)}ms  renders:${r.renderCount}  cause:${cause}`
+    );
+  }
+  return lines.join("\n");
+}
+function formatRerenders(reports) {
+  if (reports.length === 0) return "No profiling data";
+  const lines = ["Most re-renders:"];
+  for (const r of reports) {
+    const cause = r.causes[0] || "?";
+    lines.push(
+      `  ${pad(r.displayName, 20)} ${r.renderCount} renders \u2014 ${cause}`
+    );
+  }
+  return lines.join("\n");
+}
+function formatTimeline(entries) {
+  if (entries.length === 0) return "No profiling data";
+  const lines = ["Commit timeline:"];
+  for (const e of entries) {
+    lines.push(
+      `  #${e.index}  ${e.duration.toFixed(1)}ms  ${e.componentCount} components`
+    );
+  }
+  return lines.join("\n");
+}
+function formatCommitDetail(detail) {
+  const lines = [];
+  lines.push(`Commit #${detail.index}  ${detail.duration.toFixed(1)}ms  ${detail.totalComponents} components`);
+  lines.push("");
+  for (const c of detail.components) {
+    const causes = c.causes.length > 0 ? c.causes.join(", ") : "?";
+    lines.push(`  ${pad(c.displayName, 24)} self:${c.selfDuration.toFixed(1)}ms  total:${c.actualDuration.toFixed(1)}ms  ${causes}`);
+  }
+  const hidden = detail.totalComponents - detail.components.length;
+  if (hidden > 0) {
+    lines.push(`  ... ${hidden} more (use --limit to show more)`);
+  }
+  return lines.join("\n");
+}
+function formatCompactValue(val) {
+  if (val === void 0) return void 0;
+  if (val === null) return "null";
+  if (typeof val === "function") return "\u0192";
+  if (typeof val === "string") return `"${val}"`;
+  if (typeof val === "number" || typeof val === "boolean") return String(val);
+  try {
+    const s = JSON.stringify(val, replacer, 0);
+    if (s && s.length > 60) return s.slice(0, 57) + "...";
+    return s || String(val);
+  } catch {
+    return String(val);
+  }
+}
+function replacer(_key, value) {
+  if (typeof value === "function") return "\u0192";
+  return value;
+}
+function pad(s, len) {
+  return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+// src/cli.ts
+function usage() {
+  return `Usage: devtools <command> [options]
+
+Daemon:
+  start [--port 8097]           Start daemon
+  stop                          Stop daemon
+  status                        Show daemon status
+
+Components:
+  get tree [--depth N]          Component hierarchy
+  get component <@c1 | id>     Props, state, hooks
+  find <name> [--exact]         Search by display name
+  count                         Component count by type
+
+Profiling:
+  profile start [name]          Start profiling session
+  profile stop                  Stop profiling, collect data
+  profile report <@c1 | id>    Render report for component
+  profile slow [--limit N]      Slowest components (by avg)
+  profile rerenders [--limit N] Most re-rendered components
+  profile timeline [--limit N]  Commit timeline
+  profile commit <N | #N> [--limit N]  Detail for specific commit`;
+}
+function parseArgs(argv) {
+  const command = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const eqIdx = key.indexOf("=");
+      if (eqIdx !== -1) {
+        flags[key.slice(0, eqIdx)] = key.slice(eqIdx + 1);
+      } else {
+        const next = argv[i + 1];
+        if (next && !next.startsWith("--")) {
+          flags[key] = next;
+          i++;
+        } else {
+          flags[key] = true;
+        }
+      }
+    } else {
+      command.push(arg);
+    }
+  }
+  return { command, flags };
+}
+async function main() {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+  if (command.length === 0 || flags["help"]) {
+    console.log(usage());
+    process.exit(0);
+  }
+  if (typeof flags["state-dir"] === "string") {
+    setStateDir(flags["state-dir"]);
+  }
+  const cmd0 = command[0];
+  const cmd1 = command[1];
+  try {
+    if (cmd0 === "start") {
+      const port = flags["port"] ? parseInt(flags["port"], 10) : void 0;
+      await ensureDaemon(port);
+      const resp = await sendCommand({ type: "status" });
+      if (resp.ok) {
+        console.log(formatStatus(resp.data));
+      }
+      return;
+    }
+    if (cmd0 === "stop") {
+      const stopped = stopDaemon();
+      console.log(stopped ? "Daemon stopped" : "Daemon is not running");
+      return;
+    }
+    if (cmd0 === "status") {
+      const info = readDaemonInfo();
+      if (!info) {
+        console.log("Daemon is not running");
+        process.exit(1);
+      }
+      try {
+        const resp = await sendCommand({ type: "status" });
+        if (resp.ok) {
+          console.log(formatStatus(resp.data));
+        } else {
+          console.error(resp.error);
+          process.exit(1);
+        }
+      } catch {
+        console.log("Daemon is not running (stale info)");
+        process.exit(1);
+      }
+      return;
+    }
+    await ensureDaemon();
+    if (cmd0 === "get" && cmd1 === "tree") {
+      const depth = flags["depth"] ? parseInt(flags["depth"], 10) : void 0;
+      const ipcCmd = { type: "get-tree", depth };
+      const resp = await sendCommand(ipcCmd);
+      if (resp.ok) {
+        console.log(formatTree(resp.data));
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+    if (cmd0 === "get" && cmd1 === "component") {
+      const raw = command[2];
+      if (!raw) {
+        console.error("Usage: devtools get component <@c1 | id>");
+        process.exit(1);
+      }
+      const id = raw.startsWith("@") ? raw : parseInt(raw, 10);
+      if (typeof id === "number" && isNaN(id)) {
+        console.error("Usage: devtools get component <@c1 | id>");
+        process.exit(1);
+      }
+      const resp = await sendCommand({ type: "get-component", id });
+      if (resp.ok) {
+        console.log(formatComponent(resp.data, resp.label));
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+    if (cmd0 === "find") {
+      const name = command[1];
+      if (!name) {
+        console.error("Usage: devtools find <name> [--exact]");
+        process.exit(1);
+      }
+      const exact = flags["exact"] === true;
+      const resp = await sendCommand({ type: "find", name, exact });
+      if (resp.ok) {
+        console.log(formatSearchResults(resp.data));
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+    if (cmd0 === "count") {
+      const resp = await sendCommand({ type: "count" });
+      if (resp.ok) {
+        console.log(formatCount(resp.data));
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+    if (cmd0 === "profile" && cmd1 === "start") {
+      const name = command[2];
+      const resp = await sendCommand({ type: "profile-start", name });
+      if (resp.ok) {
+        console.log(resp.data);
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+    if (cmd0 === "profile" && cmd1 === "stop") {
+      const resp = await sendCommand({ type: "profile-stop" });
+      if (resp.ok) {
+        console.log(formatProfileSummary(resp.data));
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+    if (cmd0 === "profile" && cmd1 === "report") {
+      const raw = command[2];
+      if (!raw) {
+        console.error("Usage: devtools profile report <@c1 | id>");
+        process.exit(1);
+      }
+      const componentId = raw.startsWith("@") ? raw : parseInt(raw, 10);
+      if (typeof componentId === "number" && isNaN(componentId)) {
+        console.error("Usage: devtools profile report <@c1 | id>");
+        process.exit(1);
+      }
+      const resp = await sendCommand({ type: "profile-report", componentId });
+      if (resp.ok) {
+        console.log(formatProfileReport(resp.data, resp.label));
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+    if (cmd0 === "profile" && cmd1 === "slow") {
+      const limit = flags["limit"] ? parseInt(flags["limit"], 10) : void 0;
+      const resp = await sendCommand({ type: "profile-slow", limit });
+      if (resp.ok) {
+        console.log(formatSlowest(resp.data));
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+    if (cmd0 === "profile" && cmd1 === "rerenders") {
+      const limit = flags["limit"] ? parseInt(flags["limit"], 10) : void 0;
+      const resp = await sendCommand({ type: "profile-rerenders", limit });
+      if (resp.ok) {
+        console.log(formatRerenders(resp.data));
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+    if (cmd0 === "profile" && cmd1 === "commit") {
+      const raw = command[2];
+      if (!raw) {
+        console.error("Usage: devtools profile commit <N | #N>");
+        process.exit(1);
+      }
+      const index = parseInt(raw.replace(/^#/, ""), 10);
+      if (isNaN(index)) {
+        console.error("Usage: devtools profile commit <N | #N>");
+        process.exit(1);
+      }
+      const limit = flags["limit"] ? parseInt(flags["limit"], 10) : void 0;
+      const resp = await sendCommand({ type: "profile-commit", index, limit });
+      if (resp.ok) {
+        console.log(formatCommitDetail(resp.data));
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+    if (cmd0 === "profile" && cmd1 === "timeline") {
+      const limit = flags["limit"] ? parseInt(flags["limit"], 10) : void 0;
+      const resp = await sendCommand({ type: "profile-timeline", limit });
+      if (resp.ok) {
+        console.log(formatTimeline(resp.data));
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+    console.error(`Unknown command: ${command.join(" ")}`);
+    console.log(usage());
+    process.exit(1);
+  } catch (err) {
+    console.error(
+      err instanceof Error ? err.message : String(err)
+    );
+    process.exit(1);
+  }
+}
+main();
+//# sourceMappingURL=cli.js.map