agent-react-devtools 0.1.0 → 0.1.1-canary-20260210005551

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # agent-react-devtools
 
+## 0.1.1-canary-20260210005551
+
+### Patch Changes
+
+- 10ac53c: Add comprehensive README with usage examples and MIT LICENSE file
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,180 @@
+# agent-react-devtools
+
+Give your AI agent eyes into your React app. Inspect component trees, read props and state, and profile rendering performance — all from the command line. Inspired by Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) and Callstack's [agent-device](https://github.com/callstackincubator/agent-device).
+
+The project is in early development and considered experimental. Pull requests are welcome!
+
+## Features
+
+- Walk the full component tree with props, state, and hooks
+- Search for components by display name
+- Profile renders: find slow components, excessive re-renders, and commit timelines
+- Persistent background daemon that survives across CLI calls
+- Token-efficient output built for LLM consumption
+
+## Install
+
+```sh
+npm install -g agent-react-devtools
+```
+
+Or run it directly:
+
+```sh
+npx agent-react-devtools start
+```
+
+## Quick Start
+
+```sh
+agent-react-devtools start
+agent-react-devtools status
+```
+
+```
+Daemon: running (port 8097)
+Apps: 1 connected, 24 components
+Uptime: 12s
+```
+
+Browse the component tree:
+
+```sh
+agent-react-devtools get tree --depth 3
+```
+
+```
+@c1 [fn] "App"
+├─ @c2 [fn] "Header"
+│  ├─ @c3 [fn] "Nav"
+│  └─ @c4 [fn] "SearchBar"
+├─ @c5 [fn] "TodoList"
+│  ├─ @c6 [fn] "TodoItem" key="1"
+│  ├─ @c7 [fn] "TodoItem" key="2"
+│  └─ @c8 [fn] "TodoItem" key="3"
+└─ @c9 [fn] "Footer"
+```
+
+Inspect a component's props, state, and hooks:
+
+```sh
+agent-react-devtools get component @c6
+```
+
+```
+@c6 [fn] "TodoItem" key="1"
+props:
+  id: 1
+  text: "Buy groceries"
+  done: false
+  onToggle: ƒ
+hooks:
+  State: false
+  Callback: ƒ
+```
+
+Find components by name:
+
+```sh
+agent-react-devtools find TodoItem
+```
+
+```
+@c6 [fn] "TodoItem" key="1"
+@c7 [fn] "TodoItem" key="2"
+@c8 [fn] "TodoItem" key="3"
+```
+
+Profile rendering performance:
+
+```sh
+agent-react-devtools profile start
+# ... interact with the app ...
+agent-react-devtools profile stop
+agent-react-devtools profile slow
+```
+
+```
+Slowest (by avg render time):
+  TodoList             avg:4.2ms  max:8.1ms  renders:6  cause:props
+  SearchBar            avg:2.1ms  max:3.4ms  renders:12 cause:hooks
+  Header               avg:0.8ms  max:1.2ms  renders:3  cause:parent
+```
+
+## Commands
+
+### Daemon
+
+```sh
+agent-react-devtools start [--port 8097]   # Start daemon
+agent-react-devtools stop                   # Stop daemon
+agent-react-devtools status                 # Connection status
+```
+
+### Components
+
+```sh
+agent-react-devtools get tree [--depth N]          # Component hierarchy
+agent-react-devtools get component <@c1 | id>      # Props, state, hooks
+agent-react-devtools find <name> [--exact]          # Search by display name
+agent-react-devtools count                          # Component count by type
+```
+
+Components are labeled `@c1`, `@c2`, etc. You can use these labels or numeric IDs interchangeably.
+
+### Profiling
+
+```sh
+agent-react-devtools profile start [name]           # Begin a profiling session
+agent-react-devtools profile stop                    # Stop and collect data
+agent-react-devtools profile report <@c1 | id>      # Render report for a component
+agent-react-devtools profile slow [--limit N]        # Slowest components by avg duration
+agent-react-devtools profile rerenders [--limit N]   # Most re-rendered components
+agent-react-devtools profile timeline [--limit N]    # Commit timeline
+agent-react-devtools profile commit <N | #N> [--limit N]  # Single commit detail
+```
+
+## Connecting Your App
+
+Install `react-devtools-core` in your app and connect before React renders (e.g. in `src/main.tsx`):
+
+```ts
+import { initialize, connectToDevTools } from 'react-devtools-core';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+
+initialize();
+connectToDevTools({ port: 8097 });
+
+createRoot(document.getElementById('root')!).render(<App />);
+```
+
+## Using with AI Agents
+
+Add something like this to your project's `CLAUDE.md` (or equivalent agent instructions):
+
+```markdown
+## React Debugging
+
+This project uses agent-react-devtools to inspect the running React app.
+
+- `agent-react-devtools start` — start the daemon
+- `agent-react-devtools status` — check if the app is connected
+- `agent-react-devtools get tree` — see the component hierarchy
+- `agent-react-devtools get component @c1` — inspect a specific component
+- `agent-react-devtools find <Name>` — search for components
+- `agent-react-devtools profile start` / `profile stop` / `profile slow` — diagnose render performance
+```
+
+## Development
+
+```sh
+bun install        # Install dependencies
+bun run build      # Build
+bun run test       # Run tests
+bun run typecheck  # Type check
+```
+
+## License
+
+MIT

package/package.json

@@ -1,18 +1,24 @@
 {
   "name": "agent-react-devtools",
-  "version": "0.1.0",
+  "version": "0.1.1-canary-20260210005551",
   "description": "CLI tool for AI agents to inspect React component trees and profile performance",
   "type": "module",
   "bin": {
     "agent-react-devtools": "./dist/cli.js"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit"
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "cp ../../README.md ."
   },
   "repository": {
     "type": "git",

package/src/__tests__/cli-parser.test.ts

@@ -1,76 +0,0 @@
-import { describe, it, expect } from 'vitest';
-
-// Inline the parseArgs function for testing (it's not exported from cli.ts)
-function parseArgs(argv: string[]): {
-  command: string[];
-  flags: Record<string, string | boolean>;
-} {
-  const command: string[] = [];
-  const flags: Record<string, string | boolean> = {};
-
-  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 };
-}
-
-describe('CLI argument parser', () => {
-  it('should parse simple commands', () => {
-    const { command, flags } = parseArgs(['start']);
-    expect(command).toEqual(['start']);
-    expect(flags).toEqual({});
-  });
-
-  it('should parse commands with subcommands', () => {
-    const { command } = parseArgs(['get', 'tree']);
-    expect(command).toEqual(['get', 'tree']);
-  });
-
-  it('should parse --flag=value', () => {
-    const { flags } = parseArgs(['start', '--port=8098']);
-    expect(flags['port']).toBe('8098');
-  });
-
-  it('should parse --flag value', () => {
-    const { flags } = parseArgs(['start', '--port', '8098']);
-    expect(flags['port']).toBe('8098');
-  });
-
-  it('should parse boolean flags', () => {
-    const { flags } = parseArgs(['find', 'User', '--exact']);
-    expect(flags['exact']).toBe(true);
-  });
-
-  it('should parse mixed args', () => {
-    const { command, flags } = parseArgs([
-      'profile',
-      'slow',
-      '--limit',
-      '5',
-    ]);
-    expect(command).toEqual(['profile', 'slow']);
-    expect(flags['limit']).toBe('5');
-  });
-
-  it('should parse component id as positional arg', () => {
-    const { command } = parseArgs(['get', 'component', '42']);
-    expect(command).toEqual(['get', 'component', '42']);
-  });
-});

package/src/__tests__/component-tree.test.ts

@@ -1,229 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { ComponentTree } from '../component-tree.js';
-
-/**
- * Operations encoding reference (protocol v2):
- * [rendererID, rootFiberID, stringTableSize, ...stringTable, ...ops]
- *
- * String table: for each string, [length, ...charCodes]. String ID 0 = null.
- *
- * TREE_OPERATION_ADD (1):
- *   1, id, elementType, parentId, ownerID, displayNameStringID, keyStringID
- *
- * Element types (from react-devtools-shared/src/frontend/types.js):
- *   CLASS=1, FUNCTION=5, FORWARD_REF=6, HOST=7, MEMO=8, PROFILER=10, ROOT=11, SUSPENSE=12
- */
-
-/** Build a string table and return [tableData, stringIdMap] */
-function buildStringTable(strings: string[]): [number[], Map<string, number>] {
-  const idMap = new Map<string, number>();
-  const data: number[] = [];
-  for (const s of strings) {
-    const id = idMap.size + 1; // 0 is reserved for null
-    if (!idMap.has(s)) {
-      idMap.set(s, id);
-      data.push(s.length, ...Array.from(s).map((c) => c.charCodeAt(0)));
-    }
-  }
-  return [data, idMap];
-}
-
-/** Build a complete operations array with string table */
-function buildOps(
-  rendererID: number,
-  rootID: number,
-  strings: string[],
-  opsFn: (strId: (s: string) => number) => number[],
-): number[] {
-  const [tableData, idMap] = buildStringTable(strings);
-  const strId = (s: string) => idMap.get(s) || 0;
-  const ops = opsFn(strId);
-  return [rendererID, rootID, tableData.length, ...tableData, ...ops];
-}
-
-function addOp(
-  id: number,
-  elementType: number,
-  parentId: number,
-  displayNameStrId: number,
-  keyStrId: number = 0,
-): number[] {
-  return [1, id, elementType, parentId, 0, displayNameStrId, keyStrId];
-}
-
-function removeOp(...ids: number[]): number[] {
-  return [2, ids.length, ...ids];
-}
-
-function reorderOp(id: number, children: number[]): number[] {
-  return [3, id, children.length, ...children];
-}
-
-describe('ComponentTree', () => {
-  let tree: ComponentTree;
-
-  beforeEach(() => {
-    tree = new ComponentTree();
-  });
-
-  it('should add nodes from operations', () => {
-    const ops = buildOps(1, 100, ['App', 'Header', 'Footer'], (s) => [
-      ...addOp(1, 5, 0, s('App')),     // Function component at root
-      ...addOp(2, 8, 1, s('Header')),   // Memo child
-      ...addOp(3, 5, 1, s('Footer')),   // Function child
-    ]);
-
-    tree.applyOperations(ops);
-
-    expect(tree.getComponentCount()).toBe(3);
-
-    const node1 = tree.getNode(1);
-    expect(node1).toBeDefined();
-    expect(node1!.displayName).toBe('App');
-    expect(node1!.type).toBe('function');
-    expect(node1!.children).toEqual([2, 3]);
-
-    const node2 = tree.getNode(2);
-    expect(node2!.displayName).toBe('Header');
-    expect(node2!.type).toBe('memo');
-    expect(node2!.parentId).toBe(1);
-  });
-
-  it('should handle keys', () => {
-    const ops = buildOps(1, 100, ['List', 'Item', 'item-1', 'item-2'], (s) => [
-      ...addOp(1, 5, 0, s('List')),
-      ...addOp(2, 5, 1, s('Item'), s('item-1')),
-      ...addOp(3, 5, 1, s('Item'), s('item-2')),
-    ]);
-
-    tree.applyOperations(ops);
-
-    expect(tree.getNode(2)!.key).toBe('item-1');
-    expect(tree.getNode(3)!.key).toBe('item-2');
-  });
-
-  it('should remove nodes', () => {
-    const addOps = buildOps(1, 100, ['App', 'Child'], (s) => [
-      ...addOp(1, 5, 0, s('App')),
-      ...addOp(2, 5, 1, s('Child')),
-    ]);
-    tree.applyOperations(addOps);
-    expect(tree.getComponentCount()).toBe(2);
-
-    // Remove ops still need a string table (can be empty)
-    const rmOps = [1, 100, 0, ...removeOp(2)];
-    tree.applyOperations(rmOps);
-    expect(tree.getComponentCount()).toBe(1);
-    expect(tree.getNode(1)!.children).toEqual([]);
-  });
-
-  it('should reorder children', () => {
-    const ops = buildOps(1, 100, ['App', 'A', 'B', 'C'], (s) => [
-      ...addOp(1, 5, 0, s('App')),
-      ...addOp(2, 5, 1, s('A')),
-      ...addOp(3, 5, 1, s('B')),
-      ...addOp(4, 5, 1, s('C')),
-    ]);
-    tree.applyOperations(ops);
-    expect(tree.getNode(1)!.children).toEqual([2, 3, 4]);
-
-    const reorderOps = [1, 100, 0, ...reorderOp(1, [4, 2, 3])];
-    tree.applyOperations(reorderOps);
-    expect(tree.getNode(1)!.children).toEqual([4, 2, 3]);
-  });
-
-  it('should find by name (partial match)', () => {
-    const ops = buildOps(1, 100, ['App', 'UserProfile', 'UserCard', 'Footer'], (s) => [
-      ...addOp(1, 5, 0, s('App')),
-      ...addOp(2, 5, 1, s('UserProfile')),
-      ...addOp(3, 5, 1, s('UserCard')),
-      ...addOp(4, 5, 1, s('Footer')),
-    ]);
-    tree.applyOperations(ops);
-
-    const results = tree.findByName('user');
-    expect(results).toHaveLength(2);
-    expect(results.map((r) => r.displayName).sort()).toEqual([
-      'UserCard',
-      'UserProfile',
-    ]);
-  });
-
-  it('should find by name (exact match)', () => {
-    const ops = buildOps(1, 100, ['App', 'UserProfile', 'UserCard'], (s) => [
-      ...addOp(1, 5, 0, s('App')),
-      ...addOp(2, 5, 1, s('UserProfile')),
-      ...addOp(3, 5, 1, s('UserCard')),
-    ]);
-    tree.applyOperations(ops);
-
-    const results = tree.findByName('UserProfile', true);
-    expect(results).toHaveLength(1);
-    expect(results[0].displayName).toBe('UserProfile');
-  });
-
-  it('should get count by type', () => {
-    const ops = buildOps(1, 100, ['App', 'MemoComp', 'FuncComp', 'div'], (s) => [
-      ...addOp(1, 5, 0, s('App')),       // function
-      ...addOp(2, 8, 1, s('MemoComp')),   // memo
-      ...addOp(3, 5, 1, s('FuncComp')),   // function
-      ...addOp(4, 7, 1, s('div')),        // host
-    ]);
-    tree.applyOperations(ops);
-
-    const counts = tree.getCountByType();
-    expect(counts['function']).toBe(2);
-    expect(counts['memo']).toBe(1);
-    expect(counts['host']).toBe(1);
-  });
-
-  it('should get tree with depth limit', () => {
-    const ops = buildOps(1, 100, ['App', 'Level1', 'Level2', 'Level3'], (s) => [
-      ...addOp(1, 5, 0, s('App')),
-      ...addOp(2, 5, 1, s('Level1')),
-      ...addOp(3, 5, 2, s('Level2')),
-      ...addOp(4, 5, 3, s('Level3')),
-    ]);
-    tree.applyOperations(ops);
-
-    const fullTree = tree.getTree();
-    expect(fullTree).toHaveLength(4);
-
-    const shallow = tree.getTree(1);
-    expect(shallow).toHaveLength(2);
-    expect(shallow.map((n) => n.displayName)).toEqual(['App', 'Level1']);
-  });
-
-  it('should handle empty operations', () => {
-    tree.applyOperations([]);
-    expect(tree.getComponentCount()).toBe(0);
-
-    tree.applyOperations([1]);
-    expect(tree.getComponentCount()).toBe(0);
-  });
-
-  it('should handle all element types', () => {
-    const ops = buildOps(
-      1, 100,
-      ['ClassComp', 'FuncComp', 'ForwardRefComp', 'HostComp', 'MemoComp', 'ProfilerComp', 'SuspenseComp'],
-      (s) => [
-        ...addOp(1, 1, 0, s('ClassComp')),       // class = 1
-        ...addOp(2, 5, 1, s('FuncComp')),         // function = 5
-        ...addOp(3, 6, 1, s('ForwardRefComp')),   // forwardRef = 6
-        ...addOp(4, 7, 1, s('HostComp')),         // host = 7
-        ...addOp(5, 8, 1, s('MemoComp')),         // memo = 8
-        ...addOp(6, 10, 1, s('ProfilerComp')),    // profiler = 10
-        ...addOp(7, 12, 1, s('SuspenseComp')),    // suspense = 12
-      ],
-    );
-    tree.applyOperations(ops);
-
-    expect(tree.getNode(1)!.type).toBe('class');
-    expect(tree.getNode(2)!.type).toBe('function');
-    expect(tree.getNode(3)!.type).toBe('forwardRef');
-    expect(tree.getNode(4)!.type).toBe('host');
-    expect(tree.getNode(5)!.type).toBe('memo');
-    expect(tree.getNode(6)!.type).toBe('profiler');
-    expect(tree.getNode(7)!.type).toBe('suspense');
-  });
-});