tui-devtools 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +158 -56
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,97 +1,199 @@
1
1
  # tui-devtools
2
2
 
3
- DevTools for Ink TUI apps — component tree, state inspection, console capture.
3
+ All-in-one TUI automation + DevTools for terminal apps.
4
4
 
5
- Built for AI agents that need to debug terminal UI applications programmatically.
5
+ Run, screenshot, interact, and inspect — built for AI agents.
6
6
 
7
- ## Why
7
+ ## What It Does
8
8
 
9
- Tools like `agent-tui` can automate TUI apps (press keys, take screenshots), but they can only see the **screen output**. When something goes wrong, there's no way to inspect component state, view console errors, or understand the component hierarchy.
9
+ **Works with any TUI/CLI app** — no framework dependency:
10
10
 
11
- `tui-devtools` bridges this gap for **Ink (React)** apps by connecting to React DevTools protocol.
11
+ ```bash
12
+ tui-devtools start # Start daemon
13
+ tui-devtools run "htop" # Run any TUI app in a PTY
14
+ tui-devtools screenshot # Capture screen as text
15
+ tui-devtools press q # Send keystrokes
16
+ tui-devtools type "hello" # Type text
17
+ tui-devtools wait "Ready" # Wait for text to appear
18
+ tui-devtools kill-session # Kill the app
19
+ tui-devtools stop # Stop daemon
20
+ ```
12
21
 
13
- ## Quick Start
22
+ **Bonus for Ink (React) apps** — component tree & state inspection:
23
+
24
+ ```bash
25
+ tui-devtools run "DEV=true npx my-ink-app" # Run with DevTools enabled
26
+ tui-devtools tree # React component hierarchy
27
+ tui-devtools inspect MyComponent # Props, state, hooks
28
+ tui-devtools find Text # Search components by name
29
+ tui-devtools logs --level error # Captured console output
30
+ ```
31
+
32
+ ## Install
14
33
 
15
34
  ```bash
16
- # Install
17
35
  npm install -g tui-devtools
36
+ ```
37
+
38
+ ## Two Layers
39
+
40
+ | Layer | Works With | What You Get |
41
+ |-------|-----------|--------------|
42
+ | **PTY Automation** | Any TUI/CLI app | run, screenshot, press, type, wait, scroll, kill |
43
+ | **React DevTools** | Ink apps + `DEV=true` | tree, inspect, find, logs |
44
+
45
+ PTY automation works universally — Ink, Bubbletea, Ratatui, htop, vim, anything that runs in a terminal. React DevTools is an **additional layer** that activates when the app supports it.
46
+
47
+ ## Quick Start
48
+
49
+ ### Any TUI App
50
+
51
+ ```bash
52
+ tui-devtools start
53
+ tui-devtools run "npx create-next-app"
54
+ tui-devtools wait "project name"
55
+ tui-devtools type "my-app"
56
+ tui-devtools press Enter
57
+ tui-devtools screenshot
58
+ tui-devtools kill-session
59
+ tui-devtools stop
60
+ ```
61
+
62
+ ### Ink App with DevTools
18
63
 
19
- # 1. Start the DevTools server
64
+ ```bash
20
65
  tui-devtools start
66
+ tui-devtools run "DEV=true npx my-ink-app"
67
+ tui-devtools wait ">"
68
+
69
+ # Screen (what the user sees)
70
+ tui-devtools screenshot
21
71
 
22
- # 2. Run your Ink app with DEV=true
23
- DEV=true npx my-ink-app
72
+ # Structure (what React sees)
73
+ tui-devtools tree
74
+ tui-devtools inspect App --json
24
75
 
25
- # 3. Inspect
26
- tui-devtools tree # Component hierarchy
27
- tui-devtools inspect CommandMode # Props & state of a component
28
- tui-devtools logs # Console output
29
- tui-devtools logs --level error # Only errors
76
+ # Errors (what the console says)
77
+ tui-devtools logs --level error
30
78
 
31
- # 4. Cleanup
79
+ tui-devtools kill-session
32
80
  tui-devtools stop
33
81
  ```
34
82
 
35
83
  ## Commands
36
84
 
85
+ ### PTY Automation (Universal)
86
+
37
87
  | Command | Description |
38
88
  |---------|-------------|
39
- | `start` | Start DevTools server daemon |
89
+ | `start` | Start daemon (WebSocket + IPC server) |
40
90
  | `stop` | Stop daemon |
41
- | `status` | Show connection status |
42
- | `tree` | Print component tree |
43
- | `inspect <name>` | Show props/state/hooks for a component |
44
- | `find <name>` | Find components by name |
45
- | `logs` | Show captured console logs |
91
+ | `run "<command>"` | Run command in PTY (shell auto-wrapped) |
92
+ | `screenshot` | Capture current terminal screen |
93
+ | `screenshot --strip-ansi` | Without ANSI color codes |
94
+ | `press <key> [key...]` | Send keystrokes (Enter, Tab, ArrowDown, Ctrl-c, etc.) |
95
+ | `type "<text>"` | Type text |
96
+ | `wait "<text>"` | Wait for text to appear on screen |
97
+ | `wait "<text>" --timeout 5000` | With custom timeout |
98
+ | `scroll up/down [N]` | Scroll viewport |
99
+ | `kill-session` | Kill PTY process |
100
+ | `sessions` | List running PTY sessions |
101
+ | `status` | Show daemon & connection status |
102
+
103
+ ### React DevTools (Ink Apps Only)
46
104
 
47
- ## With agent-tui (AI Agent Workflow)
105
+ | Command | Description |
106
+ |---------|-------------|
107
+ | `tree` | Component hierarchy |
108
+ | `tree --depth N` | Limit depth |
109
+ | `tree --json` | JSON output |
110
+ | `inspect <name>` | Props, state, hooks |
111
+ | `inspect --id <N>` | By fiber ID |
112
+ | `find <name>` | Search components by name |
113
+ | `logs` | Captured console.log/warn/error |
114
+ | `logs --level error` | Filter by level |
115
+ | `logs --tail N` | Last N entries |
116
+
117
+ > React DevTools requires: `react-devtools-core` installed in the app + `DEV=true` env var.
118
+
119
+ ## Key Names
120
+
121
+ | Key | Name |
122
+ |-----|------|
123
+ | Enter | `Enter` |
124
+ | Tab | `Tab` |
125
+ | Escape | `Escape` |
126
+ | Arrows | `ArrowUp` `ArrowDown` `ArrowLeft` `ArrowRight` |
127
+ | Backspace | `Backspace` |
128
+ | Space | `Space` |
129
+ | Ctrl+C | `Ctrl-c` |
130
+ | Multiple | `press ArrowDown ArrowDown Enter` |
131
+
132
+ ## Session Management
48
133
 
49
134
  ```bash
50
- # Start devtools first
51
- tui-devtools -s myapp start
52
-
53
- # Start the TUI app
54
- agent-tui run -s myapp "DEV=true npx my-ink-app"
55
-
56
- # Visual: what's on screen
57
- agent-tui -s myapp screenshot
58
-
59
- # Structural: what's in React
60
- tui-devtools -s myapp tree
61
-
62
- # Debug: what went wrong
63
- tui-devtools -s myapp logs --level error
64
- tui-devtools -s myapp inspect MyComponent --json
135
+ # Daemon-level sessions (-s) for isolation
136
+ tui-devtools -s project1 start
137
+ tui-devtools -s project2 start --port 8098
138
+
139
+ # Multiple PTY sessions within one daemon (--sid)
140
+ tui-devtools -s test run "app1" --sid app1
141
+ tui-devtools -s test run "app2" --sid app2
142
+ tui-devtools -s test screenshot --sid app1
65
143
  ```
66
144
 
67
- ## How It Works
145
+ ## Output Formats
68
146
 
69
- ```
70
- Ink App (DEV=true) tui-devtools daemon
71
- ───────────────── ──────────────────
72
- react-devtools-core WebSocket server (:8097)
73
- connectToDevTools() ──WebSocket──► Parse fiber tree operations
74
- Store component tree + logs
75
- │
76
- Unix socket IPC
77
- │
78
- CLI commands ◄── AI agent
147
+ ```bash
148
+ tui-devtools screenshot # Text (human-readable)
149
+ tui-devtools screenshot --json # JSON (automation)
150
+ tui-devtools tree --json # JSON component tree
151
+ tui-devtools sessions --json # JSON session list
79
152
  ```
80
153
 
81
- ## Options
154
+ ## How It Works
82
155
 
83
156
  ```
84
- -s, --session <name> Session name (default: "default")
85
- -p, --port <port> DevTools port (default: 8097)
86
- --json JSON output for all commands
157
+ ┌─────────────────────────────────────────────────────┐
158
+ │ tui-devtools daemon │
159
+ │ │
160
+ │ ┌──────────────┐ ┌───────────────────────────┐ │
161
+ │ │ PTY Manager │ │ React DevTools Server │ │
162
+ │ │ (node-pty + │ │ (WebSocket :8097) │ │
163
+ │ │ xterm) │ │ │ │
164
+ │ │ │ │ Ink app ──ws──► fiber tree │ │
165
+ │ │ Any TUI app │ │ ► console │ │
166
+ │ └──────┬───────┘ └───────────┬───────────────┘ │
167
+ │ │ │ │
168
+ │ └────────┬───────────────┘ │
169
+ │ │ Unix socket IPC │
170
+ └──────────────────┼──────────────────────────────────┘
171
+ │
172
+ CLI commands ◄── AI agent / human
87
173
  ```
88
174
 
89
175
  ## Requirements
90
176
 
91
177
  - Node.js >= 18
92
- - Target app must use **Ink** (React-based TUI framework)
93
- - `react-devtools-core` must be installed in the target app
94
- - Run the app with `DEV=true` environment variable
178
+ - macOS or Linux (PTY support)
179
+
180
+ **For React DevTools features (optional):**
181
+ - Target app must use Ink (React-based TUI)
182
+ - `react-devtools-core` package installed in the app
183
+ - App launched with `DEV=true` environment variable
184
+
185
+ ## Troubleshooting
186
+
187
+ ```bash
188
+ # posix_spawnp failed (macOS)
189
+ chmod +x $(npm root -g)/tui-devtools/node_modules/node-pty/prebuilds/darwin-*/spawn-helper
190
+
191
+ # Daemon status
192
+ tui-devtools -s test status
193
+
194
+ # Debug logs
195
+ cat ~/.tui-devtools/test.log
196
+ ```
95
197
 
96
198
  ## License
97
199
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tui-devtools",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "All-in-one TUI automation + DevTools — run, screenshot, interact, and inspect React component trees in terminal apps. Built for AI agents.",
5
5
  "repository": {
6
6
  "type": "git",