tauri-agent-tools 0.1.0

package/.agents/skills/tauri-agent-tools/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: tauri-agent-tools
+description: CLI for inspecting Tauri desktop apps — DOM queries, screenshots, IPC/console monitoring, storage, and page state
+version: 0.1.0
+tags: [tauri, desktop, debugging, screenshot, dom, inspection]
+---
+
+# tauri-agent-tools
+
+CLI tool for agent-driven inspection of Tauri desktop applications. All commands are **read-only** — no input injection, no writes, no side effects.
+
+## Prerequisites
+
+```bash
+# Check if installed
+which tauri-agent-tools
+
+# Install globally if missing
+npm install -g tauri-agent-tools
+```
+
+**System dependencies by platform:**
+
+| Platform | Requirements |
+|----------|-------------|
+| Linux X11 | `xdotool`, `imagemagick` (`sudo apt install xdotool imagemagick`) |
+| Linux Wayland/Sway | `swaymsg`, `grim`, `imagemagick` |
+| macOS | `imagemagick` (`brew install imagemagick`), Screen Recording permission |
+
+## Bridge vs Standalone
+
+Some commands require the Rust dev bridge running inside the Tauri app. Others work standalone.
+
+**Bridge required** (needs running Tauri app with bridge):
+`screenshot --selector`, `dom`, `eval`, `wait --selector`, `wait --eval`, `ipc-monitor`, `console-monitor`, `storage`, `page-state`
+
+**Standalone** (no bridge needed):
+`screenshot --title` (full window only), `wait --title`, `list-windows`, `info`
+
+The bridge auto-discovers via token files in `/tmp/tauri-dev-bridge-*.token`. No manual port/token configuration needed.
+
+## Core Workflows
+
+### Inspect DOM then screenshot an element
+
+```bash
+# 1. Find the target app
+tauri-agent-tools list-windows --tauri
+
+# 2. Explore DOM structure
+tauri-agent-tools dom --depth 3
+
+# 3. Narrow down to a specific subtree
+tauri-agent-tools dom ".sidebar" --depth 2 --styles
+
+# 4. Screenshot the element
+tauri-agent-tools screenshot --selector ".sidebar .nav-item.active" -o /tmp/nav.png
+```
+
+### Monitor IPC calls
+
+```bash
+# Watch all IPC calls for 10 seconds
+tauri-agent-tools ipc-monitor --duration 10000 --json
+
+# Filter to specific commands
+tauri-agent-tools ipc-monitor --filter "get_*" --duration 5000 --json
+```
+
+### Diagnose app state
+
+```bash
+# Check page URL, title, viewport, scroll position
+tauri-agent-tools page-state --json
+
+# Inspect storage
+tauri-agent-tools storage --type local --json
+
+# Check console for errors
+tauri-agent-tools console-monitor --level error --duration 5000 --json
+```
+
+## Command Reference
+
+| Command | Key Flags | Bridge? | Description |
+|---------|-----------|---------|-------------|
+| `screenshot` | `--selector <css>`, `--title <regex>`, `-o <path>`, `--max-width <n>` | selector: yes, title: no | Capture window or DOM element screenshot |
+| `dom` | `[selector]`, `--depth <n>`, `--styles`, `--mode accessibility`, `--json` | yes | Query DOM structure |
+| `eval` | `<js-expression>` | yes | Evaluate JavaScript in webview |
+| `wait` | `--selector <css>`, `--eval <js>`, `--title <regex>`, `--timeout <ms>` | selector/eval: yes | Wait for a condition |
+| `list-windows` | `--tauri`, `--json` | no | List visible windows |
+| `info` | `--title <regex>`, `--json` | no | Window geometry and display info |
+| `ipc-monitor` | `--filter <cmd>`, `--duration <ms>`, `--json` | yes | Monitor Tauri IPC calls |
+| `console-monitor` | `--level <lvl>`, `--filter <regex>`, `--duration <ms>`, `--json` | yes | Monitor console output |
+| `storage` | `--type <local\|session\|cookies\|all>`, `--key <name>`, `--json` | yes | Inspect browser storage |
+| `page-state` | `--json` | yes | URL, title, viewport, scroll, document size |
+
+## Important Notes
+
+- **All read-only.** No commands modify app state, inject input, or write to storage.
+- **Use `--json`** for structured, parseable output in automation.
+- **Always use `--duration`** with `ipc-monitor` and `console-monitor` — without it, they run indefinitely.
+- **`screenshot --selector`** requires both the bridge AND platform screenshot tools (`imagemagick`).
+- **One bridge at a time.** Auto-discovery picks the first token file found. If multiple Tauri apps run simultaneously, use `--port` and `--token` explicitly.

package/.agents/skills/tauri-bridge-setup/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: tauri-bridge-setup
+description: How to add the tauri-agent-tools Rust dev bridge to a Tauri application
+version: 0.1.0
+tags: [tauri, rust, bridge, setup, integration]
+---
+
+# Tauri Dev Bridge Setup
+
+Add the dev bridge to a Tauri app so `tauri-agent-tools` can inspect DOM, evaluate JS, monitor IPC, and take element screenshots.
+
+The bridge runs **only in debug builds** and is stripped from release builds automatically.
+
+## Step 1 — Add Cargo dependencies
+
+Add to your Tauri app's `src-tauri/Cargo.toml` under `[dependencies]`:
+
+```toml
+tiny_http = "0.12"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+scopeguard = "1"
+rand = "0.8"
+```
+
+## Step 2 — Copy the bridge module
+
+Copy `dev_bridge.rs` from the tauri-agent-tools package into your project:
+
+```bash
+# Find the installed package location
+TOOLS_DIR=$(npm root -g)/tauri-agent-tools
+
+# Copy the bridge module
+cp "$TOOLS_DIR/examples/tauri-bridge/src/dev_bridge.rs" src-tauri/src/dev_bridge.rs
+```
+
+If installed locally (not globally):
+
+```bash
+cp node_modules/tauri-agent-tools/examples/tauri-bridge/src/dev_bridge.rs src-tauri/src/dev_bridge.rs
+```
+
+## Step 3 — Wire up in main.rs
+
+Add the module declaration and start the bridge in your `src-tauri/src/main.rs`:
+
+```rust
+mod dev_bridge;
+
+fn main() {
+    tauri::Builder::default()
+        .setup(|app| {
+            if cfg!(debug_assertions) {
+                if let Err(e) = dev_bridge::start_bridge(app.handle()) {
+                    eprintln!("Warning: Failed to start dev bridge: {e}");
+                }
+            }
+            Ok(())
+        })
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+If you already have a `.setup()` call, add the `if cfg!(debug_assertions) { ... }` block inside it.
+
+## Step 4 — Verify
+
+Build and run the Tauri app in dev mode, then:
+
+```bash
+# Should show your app with a bridge indicator
+tauri-agent-tools list-windows --tauri
+
+# Should return DOM tree
+tauri-agent-tools dom --depth 2
+```
+
+Both commands succeeding confirms the bridge is working.
+
+## Troubleshooting
+
+**"No bridge found" error:**
+- Is the app running in dev/debug mode? The bridge only starts when `cfg!(debug_assertions)` is true.
+- Check for token files: `ls /tmp/tauri-dev-bridge-*.token`
+- The app process must be running — the bridge starts during `setup()`.
+
+**Stale token files:**
+- If the app crashed without cleanup, old token files may remain: `rm /tmp/tauri-dev-bridge-*.token`
+- Restart the Tauri app after cleaning.
+
+**Port conflicts:**
+- The bridge picks a random port. If it fails, check the app's stderr for "Failed to start dev bridge".
+- Ensure no firewall blocks localhost connections.

package/AGENTS.md

@@ -0,0 +1,30 @@
+# tauri-agent-tools
+
+CLI tool for agent-driven inspection of Tauri desktop applications. **Not an MCP server** — invoke commands directly via shell.
+
+## Agent Skills
+
+This package includes two [Agent Skills](https://agentskills.io):
+
+| Skill | Path | Purpose |
+|-------|------|---------|
+| `tauri-agent-tools` | `.agents/skills/tauri-agent-tools/SKILL.md` | Using the 11 CLI commands to inspect Tauri apps |
+| `tauri-bridge-setup` | `.agents/skills/tauri-bridge-setup/SKILL.md` | Adding the Rust dev bridge to a Tauri project |
+
+## Quick Reference
+
+**Install:** `npm install -g tauri-agent-tools`
+
+**All commands are read-only.** No input injection, no writes, no side effects.
+
+**Standalone commands** (no bridge needed):
+`list-windows`, `info`, `screenshot --title`, `wait --title`
+
+**Bridge-required commands** (Tauri app must have dev bridge running):
+`dom`, `eval`, `screenshot --selector`, `wait --selector/--eval`, `ipc-monitor`, `console-monitor`, `storage`, `page-state`
+
+**Bridge auto-discovery:** The CLI finds the running bridge via token files in `/tmp/tauri-dev-bridge-*.token`. No manual configuration needed.
+
+**Structured output:** Use `--json` on any command for machine-readable output.
+
+**Monitors:** Always pass `--duration <ms>` to `ipc-monitor` and `console-monitor` to avoid indefinite execution.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cesar Andres Lopez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+<div align="center">
+
+# tauri-agent-tools
+
+**Agent-driven inspection toolkit for Tauri desktop apps**
+
+11 read-only commands to screenshot, inspect, and monitor Tauri apps from the CLI.
+
+[![CI](https://github.com/cesarandreslopez/tauri-agent-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/cesarandreslopez/tauri-agent-tools/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/tauri-agent-tools.svg)](https://www.npmjs.com/package/tauri-agent-tools)
+[![npm downloads](https://img.shields.io/npm/dm/tauri-agent-tools.svg)](https://www.npmjs.com/package/tauri-agent-tools)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node >= 20](https://img.shields.io/badge/Node-%3E%3D20-green.svg)](https://nodejs.org)
+
+</div>
+
+## The Problem
+
+Debugging frontend issues in Tauri desktop apps requires manually screenshotting, cropping, and describing what you see. Existing tools either hijack your cursor (xcap-based), render DOM to canvas (html2canvas — can't capture WebGL/video/canvas), or have no authentication.
+
+## The Solution
+
+Combine a bridge's knowledge of element positions (`getBoundingClientRect`) with real pixel screenshots (`import -window` + ImageMagick crop). No other tool does this.
+
+```bash
+# Screenshot a specific DOM element with real pixels
+tauri-agent-tools screenshot --selector ".wf-toolbar" -o /tmp/toolbar.png
+tauri-agent-tools screenshot --selector "#canvas-area" -o /tmp/canvas.png
+
+# Explore DOM structure first
+tauri-agent-tools dom --depth 3
+tauri-agent-tools dom ".wf-canvas" --depth 4
+
+# Then screenshot what you found
+tauri-agent-tools screenshot --selector ".wf-canvas .block-node" -o /tmp/block.png
+```
+
+## Install
+
+```bash
+npm install -g tauri-agent-tools
+```
+
+**System requirements:**
+- **Linux X11:** `xdotool`, `imagemagick` (`sudo apt install xdotool imagemagick`)
+- **Linux Wayland/Sway:** `swaymsg`, `grim`, `imagemagick`
+- **macOS:** `imagemagick` (`brew install imagemagick`) — all other tools are built-in. Grant Screen Recording permission in System Settings → Privacy & Security → Screen Recording.
+
+## Quick Start
+
+### 1. Add the bridge to your Tauri app
+
+See [rust-bridge/README.md](rust-bridge/README.md) for step-by-step integration (~120 lines of Rust).
+
+The bridge runs a localhost-only, token-authenticated HTTP server during development. It auto-cleans up on exit.
+
+### 2. Use the CLI
+
+```bash
+# DOM-targeted screenshot (needs bridge)
+tauri-agent-tools screenshot --selector ".toolbar" -o /tmp/toolbar.png
+tauri-agent-tools screenshot --selector "#main-canvas" --max-width 800 -o /tmp/canvas.png
+
+# Full window screenshot (no bridge needed, works with any window)
+tauri-agent-tools screenshot --title "My App" -o /tmp/full.png
+
+# Explore DOM
+tauri-agent-tools dom --depth 3
+tauri-agent-tools dom ".sidebar" --depth 2 --styles
+
+# Evaluate JS
+tauri-agent-tools eval "document.title"
+tauri-agent-tools eval "document.querySelectorAll('.item').length"
+
+# Wait for conditions
+tauri-agent-tools wait --selector ".toast-message" --timeout 5000
+tauri-agent-tools wait --title "My App" --timeout 10000
+
+# Window info
+tauri-agent-tools info --title "My App" --json
+```
+
+## Commands
+
+### `screenshot`
+
+Capture a screenshot of a window or DOM element.
+
+| Option | Description |
+|--------|-------------|
+| `-s, --selector <css>` | CSS selector — screenshot just this element (requires bridge) |
+| `-t, --title <regex>` | Window title to match |
+| `-o, --output <path>` | Output file path (default: auto-named) |
+| `--format <png\|jpg>` | Output format (default: png) |
+| `--max-width <number>` | Resize to max width |
+| `--port <number>` | Bridge port (auto-discover if omitted) |
+| `--token <string>` | Bridge token (auto-discover if omitted) |
+
+### `dom`
+
+Query DOM structure from the Tauri app.
+
+| Option | Description |
+|--------|-------------|
+| `[selector]` | Root element to explore (default: body) |
+| `--mode <mode>` | Output mode: `dom` (default) or `accessibility` |
+| `--depth <number>` | Max child depth (default: 3) |
+| `--tree` | Compact tree view (default) |
+| `--styles` | Include computed styles |
+| `--count` | Just output match count |
+| `--first` | Only return first match |
+| `--json` | Full structured JSON output |
+
+### `eval`
+
+Evaluate a JavaScript expression in the Tauri app.
+
+```bash
+tauri-agent-tools eval "document.title"
+```
+
+### `wait`
+
+Wait for a condition to be met.
+
+| Option | Description |
+|--------|-------------|
+| `-s, --selector <css>` | Wait for CSS selector to match |
+| `-e, --eval <js>` | Wait for JS expression to be truthy |
+| `-t, --title <regex>` | Wait for window with title (no bridge) |
+| `--timeout <ms>` | Maximum wait time (default: 10000) |
+| `--interval <ms>` | Polling interval (default: 500) |
+
+### `info`
+
+Show window geometry and display server info.
+
+```bash
+tauri-agent-tools info --title "My App" --json
+```
+
+### `list-windows`
+
+List all visible windows, marking Tauri apps.
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON |
+| `--tauri` | Only show Tauri app windows |
+
+### `ipc-monitor`
+
+Monitor Tauri IPC calls in real-time (read-only). Monkey-patches `window.__TAURI__.core.invoke` to capture calls, then polls and restores on exit.
+
+| Option | Description |
+|--------|-------------|
+| `--filter <command>` | Only show specific IPC commands (supports `*` wildcards) |
+| `--interval <ms>` | Poll interval in milliseconds (default: 500) |
+| `--duration <ms>` | Auto-stop after N milliseconds |
+| `--json` | Output one JSON object per line |
+
+### `console-monitor`
+
+Monitor console output (log/warn/error/info/debug) in real-time. Monkey-patches console methods to capture entries, then polls and restores on exit.
+
+| Option | Description |
+|--------|-------------|
+| `--level <level>` | Filter by level (log, warn, error, info, debug) |
+| `--filter <regex>` | Filter messages by regex pattern |
+| `--interval <ms>` | Poll interval in milliseconds (default: 500) |
+| `--duration <ms>` | Auto-stop after N milliseconds |
+| `--json` | Output one JSON object per line |
+
+### `storage`
+
+Inspect localStorage, sessionStorage, and cookies from the Tauri webview. One-shot read — no writes.
+
+| Option | Description |
+|--------|-------------|
+| `--type <type>` | Storage type: `local`, `session`, `cookies`, `all` (default: all) |
+| `--key <name>` | Get a specific key's value |
+| `--json` | Output as JSON |
+
+### `page-state`
+
+Query webview page state: URL, title, viewport, scroll position, document size, and Tauri detection.
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON |
+
+## How It Works
+
+```
+screenshot --selector ".toolbar" --title "My App"
+  │
+  ├─► Bridge client ──► POST /eval ──► getBoundingClientRect(".toolbar")
+  │                                     returns { x, y, width, height }
+  │
+  ├─► Platform adapter ──► import -window WID png:- (capture full window)
+  │
+  ├─► Compute crop region:
+  │     element rect from bridge + viewport offset (outerHeight - innerHeight)
+  │
+  └─► convert png:- -crop WxH+X+Y +repage png:- (crop to element)
+```
+
+The crop accounts for window decoration (title bar, borders) by comparing `window.innerHeight` from the bridge with the actual window height from `xdotool`.
+
+## Platform Support
+
+| Platform | Display Server | Status |
+|----------|---------------|--------|
+| Linux | X11 | Supported |
+| Linux | Wayland (Sway) | Supported |
+| macOS | CoreGraphics | Supported |
+| Windows | - | Planned |
+
+## Design Decisions
+
+### Why no write operations
+
+All commands are read-only. We don't inject clicks, keystrokes, scroll events, or any input into the Tauri webview. Reasons:
+
+- **Native input injection is risky.** X11 input injection (e.g. via `xdotool`) operates system-wide, not per-window — it can grab the mouse cursor and require a hard reboot to recover.
+- **Simulated events don't work.** `dispatchEvent()` creates events with `isTrusted: false`. Frameworks (React, Vue, Angular) and browsers reject untrusted events for security-sensitive operations.
+- **Input injection is fragile across platforms.** X11 (`xdotool`), Wayland (no global input protocol by design), and macOS (requires Accessibility permission + sandbox restrictions) each have different security models. A cross-platform injection layer would be unreliable.
+- **Read-only is a safer contract for dev tool automation.** Tools that can only observe cannot corrupt application state, trigger unintended side effects, or create security vulnerabilities in CI pipelines.
+
+### Why no MCP server mode
+
+This tool is a CLI that runs commands and exits — not a persistent MCP server. Reasons:
+
+- **No daemon to manage.** No port to monitor, no process to restart, no state to leak between sessions.
+- **No `.mcp.json` auto-start risk.** MCP servers start automatically when a project opens in supporting editors. A dev tool that auto-starts and connects to your running app on project open is a footgun.
+- **No transport complexity.** No WebSocket/stdio state machine, no reconnection logic, no transport-layer bugs.
+- **Composable with any agent framework.** Commands return structured output (`--json`) that any tool-use system can call directly. Define each command as a tool — no MCP SDK dependency required.
+
+## Safety Guarantees
+
+- **No input injection** — no mouse moves, clicks, keystrokes, or cursor changes
+- **No xcap crate** — uses `xdotool` + ImageMagick `import` (read-only X11 operations)
+- **No daemon** — CLI runs and exits, no background processes
+- **No `.mcp.json`** — never auto-starts
+- **All OS interactions read-only** — `xdotool search`, `getwindowgeometry`, `import -window`
+- **Token authenticated bridge** — random 32-char token, localhost-only
+- **`execFile` (array args)** — never `exec` (shell string), prevents command injection
+- **Window ID validated** — must match `/^\d+$/`
+
+## Agent Integration
+
+This package ships [Agent Skills](https://agentskills.io) so AI coding agents can automatically learn how to use the CLI and set up the bridge.
+
+| Skill | Description |
+|-------|-------------|
+| `tauri-agent-tools` | Using all 11 CLI commands to inspect Tauri apps |
+| `tauri-bridge-setup` | Adding the Rust dev bridge to a Tauri project |
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+Claude Code auto-discovers skills from `.agents/skills/` in the current project. If you installed `tauri-agent-tools` globally and want skills available everywhere:
+
+```bash
+cp -r "$(npm root -g)/tauri-agent-tools/.agents" ~/.agents
+```
+</details>
+
+<details>
+<summary><strong>Codex</strong></summary>
+
+Codex reads `AGENTS.md` at the repo root and skills from `node_modules`. Install locally:
+
+```bash
+npm install tauri-agent-tools
+```
+
+Codex will pick up `AGENTS.md` and `.agents/skills/` automatically.
+</details>
+
+<details>
+<summary><strong>Cursor / VS Code Copilot</strong></summary>
+
+Copy skills into your project so the agent can discover them:
+
+```bash
+cp -r node_modules/tauri-agent-tools/.agents .agents
+```
+
+Or if installed globally:
+
+```bash
+cp -r "$(npm root -g)/tauri-agent-tools/.agents" .agents
+```
+</details>
+
+<details>
+<summary><strong>Other agents</strong></summary>
+
+Any [agentskills.io](https://agentskills.io)-compatible agent can read the skills from `.agents/skills/` in this package. Install globally or locally and point the agent at the skill directory.
+</details>
+
+## Documentation
+
+Full documentation is available at the [docs site](https://cesarandreslopez.github.io/tauri-agent-tools/):
+
+- [Installation](https://cesarandreslopez.github.io/tauri-agent-tools/getting-started/installation/) — system requirements and setup
+- [Quick Start](https://cesarandreslopez.github.io/tauri-agent-tools/getting-started/quick-start/) — get running in 5 minutes
+- [Bridge Setup](https://cesarandreslopez.github.io/tauri-agent-tools/getting-started/bridge-setup/) — integrate the Rust bridge into your Tauri app
+- [Command Reference](https://cesarandreslopez.github.io/tauri-agent-tools/commands/) — all 11 commands with examples
+- [Platform Support](https://cesarandreslopez.github.io/tauri-agent-tools/platform-support/) — X11, Wayland, macOS details
+- [Architecture](https://cesarandreslopez.github.io/tauri-agent-tools/architecture/overview/) — how it works under the hood
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
+- Development setup and prerequisites
+- Code style and conventions
+- Branch naming and commit message format
+- Pull request process
+
+## Community
+
+- [Open an issue](https://github.com/cesarandreslopez/tauri-agent-tools/issues) for bugs or feature requests
+- Star the repo if you find it useful
+
+## License
+
+MIT

package/dist/bridge/client.d.ts

@@ -0,0 +1,15 @@
+import type { BridgeConfig, ElementRect } from '../types.js';
+export declare class BridgeClient {
+    private baseUrl;
+    private token;
+    constructor(config: BridgeConfig);
+    eval(js: string, timeout?: number): Promise<unknown>;
+    getElementRect(selector: string): Promise<ElementRect | null>;
+    getViewportSize(): Promise<{
+        width: number;
+        height: number;
+    }>;
+    getDocumentTitle(): Promise<string>;
+    getAccessibilityTree(selector?: string, depth?: number): Promise<unknown>;
+    ping(): Promise<boolean>;
+}