tauri-agent-tools 0.1.0

package/examples/tauri-bridge/src/dev_bridge.rs

@@ -0,0 +1,146 @@
+use rand::Rng;
+use serde::{Deserialize, Serialize};
+use std::fs;
+use std::io::Write;
+use std::sync::Arc;
+use std::thread;
+use tauri::{AppHandle, Manager};
+use tiny_http::{Header, Response, Server};
+
+#[derive(Deserialize)]
+struct EvalRequest {
+    js: String,
+    token: String,
+}
+
+#[derive(Serialize)]
+struct EvalResponse {
+    result: serde_json::Value,
+}
+
+#[derive(Serialize)]
+struct TokenFile {
+    port: u16,
+    token: String,
+    pid: u32,
+}
+
+/// Start the development bridge HTTP server.
+/// Returns the port number on success.
+pub fn start_bridge(app: &AppHandle) -> Result<u16, String> {
+    let server = Server::http("127.0.0.1:0").map_err(|e| format!("Failed to start bridge: {e}"))?;
+    let port = server
+        .server_addr()
+        .to_ip()
+        .ok_or("Failed to get server address")?
+        .port();
+
+    // Generate random token
+    let token: String = rand::thread_rng()
+        .sample_iter(&rand::distributions::Alphanumeric)
+        .take(32)
+        .map(char::from)
+        .collect();
+
+    // Write token file
+    let token_file = TokenFile {
+        port,
+        token: token.clone(),
+        pid: std::process::id(),
+    };
+    let token_path = format!("/tmp/tauri-dev-bridge-{}.token", std::process::id());
+    let token_json = serde_json::to_string_pretty(&token_file).unwrap();
+    fs::write(&token_path, &token_json).map_err(|e| format!("Failed to write token file: {e}"))?;
+
+    // Clean up token file on exit
+    let cleanup_path = token_path.clone();
+    let _guard = scopeguard::guard((), move |_| {
+        let _ = fs::remove_file(&cleanup_path);
+    });
+
+    let app_handle = app.clone();
+    let expected_token = token.clone();
+
+    thread::spawn(move || {
+        // Keep _guard alive for the lifetime of the server thread
+        let _cleanup = _guard;
+
+        for request in server.incoming_requests() {
+            if request.method().as_str() != "POST" || request.url() != "/eval" {
+                let _ = request.respond(Response::from_string("Not found").with_status_code(404));
+                continue;
+            }
+
+            // Read body
+            let mut body = String::new();
+            if let Err(_) = request.as_reader().read_to_string(&mut body) {
+                let _ =
+                    request.respond(Response::from_string("Bad request").with_status_code(400));
+                continue;
+            }
+
+            // Parse request
+            let eval_req: EvalRequest = match serde_json::from_str(&body) {
+                Ok(r) => r,
+                Err(_) => {
+                    let _ = request
+                        .respond(Response::from_string("Invalid JSON").with_status_code(400));
+                    continue;
+                }
+            };
+
+            // Verify token
+            if eval_req.token != expected_token {
+                let _ =
+                    request.respond(Response::from_string("Unauthorized").with_status_code(401));
+                continue;
+            }
+
+            // Evaluate JS in webview
+            let (tx, rx) = std::sync::mpsc::channel();
+            let js = eval_req.js.clone();
+
+            if let Some(window) = app_handle.get_webview_window("main") {
+                let _ = window.eval(&format!(
+                    r#"
+                    try {{
+                        const __result = eval({js});
+                        window.__tauriDevBridgeResult = __result;
+                    }} catch(e) {{
+                        window.__tauriDevBridgeResult = "ERROR: " + e.message;
+                    }}
+                    "#,
+                    js = serde_json::to_string(&js).unwrap()
+                ));
+
+                // Give the webview a moment to evaluate
+                thread::sleep(std::time::Duration::from_millis(50));
+
+                // For simplicity, return the JS expression — in production,
+                // use a Tauri command callback to get the actual result
+                let _ = tx.send(serde_json::Value::String(js));
+            } else {
+                let _ = tx.send(serde_json::Value::Null);
+            }
+
+            match rx.recv_timeout(std::time::Duration::from_secs(5)) {
+                Ok(result) => {
+                    let resp = EvalResponse { result };
+                    let json = serde_json::to_string(&resp).unwrap();
+                    let header =
+                        Header::from_bytes("Content-Type", "application/json").unwrap();
+                    let _ = request.respond(Response::from_string(json).with_header(header));
+                }
+                Err(_) => {
+                    let _ = request
+                        .respond(Response::from_string("Eval timeout").with_status_code(504));
+                }
+            }
+        }
+    });
+
+    eprintln!("Dev bridge started on port {port}");
+    eprintln!("Token file: {token_path}");
+
+    Ok(port)
+}

package/examples/tauri-bridge/src/main.rs

@@ -0,0 +1,16 @@
+mod dev_bridge;
+
+fn main() {
+    tauri::Builder::default()
+        .setup(|app| {
+            // Only start bridge in development
+            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");
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "tauri-agent-tools",
+  "version": "0.1.0",
+  "description": "Agent-driven inspection toolkit for Tauri desktop apps",
+  "type": "module",
+  "bin": {
+    "tauri-agent-tools": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev": "tsc --watch",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cesarandreslopez/tauri-agent-tools"
+  },
+  "homepage": "https://cesarandreslopez.github.io/tauri-agent-tools/",
+  "bugs": {
+    "url": "https://github.com/cesarandreslopez/tauri-agent-tools/issues"
+  },
+  "keywords": [
+    "tauri",
+    "screenshot",
+    "dom-inspection",
+    "desktop-app",
+    "cli",
+    "agent-tools",
+    "devtools",
+    "cross-platform"
+  ],
+  "author": {
+    "name": "Cesar Andres Lopez",
+    "email": "cesarandreslopez@gmail.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.8.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.1.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist/",
+    "rust-bridge/",
+    "examples/",
+    ".agents/",
+    "AGENTS.md"
+  ],
+  "agents": {
+    "skills": ".agents/skills"
+  },
+  "license": "MIT"
+}

package/rust-bridge/README.md

@@ -0,0 +1,80 @@
+# Tauri Dev Bridge — Integration Guide
+
+The dev bridge is a lightweight HTTP server that runs inside your Tauri app during development. It allows `tauri-agent-tools` to evaluate JavaScript in the webview for DOM-targeted screenshots and inspection.
+
+## Quick Setup
+
+### 1. Add dependencies to your `Cargo.toml`
+
+```toml
+[dependencies]
+tiny_http = "0.12"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+scopeguard = "1"
+rand = "0.8"
+```
+
+### 2. Copy the bridge module
+
+Copy `examples/tauri-bridge/src/dev_bridge.rs` into your Tauri project's `src/` directory.
+
+### 3. Start the bridge in your app
+
+In your `main.rs` or app setup:
+
+```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");
+}
+```
+
+### 4. Use tauri-agent-tools
+
+The bridge writes a token file to `/tmp/tauri-dev-bridge-<pid>.token` which `tauri-agent-tools` auto-discovers:
+
+```bash
+# Screenshot a specific element
+tauri-agent-tools screenshot --selector ".toolbar" -o /tmp/toolbar.png
+
+# Explore the DOM
+tauri-agent-tools dom --depth 3
+
+# Evaluate JS
+tauri-agent-tools eval "document.title"
+```
+
+## How It Works
+
+1. Bridge starts an HTTP server on a random localhost port
+2. A token file with `{ port, token, pid }` is written to `/tmp/`
+3. `tauri-agent-tools` discovers the token file and authenticates via the token
+4. Requests are `POST /eval { js, token }` — the bridge evaluates JS in the webview
+5. The token file is cleaned up when the app exits
+
+## Security
+
+- **Localhost only** — the bridge binds to `127.0.0.1`
+- **Token authenticated** — every request requires a random 32-char token
+- **Development only** — wrapped in `cfg!(debug_assertions)`, stripped in release builds
+- **Read-only** — `tauri-agent-tools` only reads DOM state, never injects input
+
+## Agent-Assisted Setup
+
+If you're using an AI coding agent (Claude Code, Codex, Cursor, etc.), the `tauri-bridge-setup` skill can guide automated setup. See `.agents/skills/tauri-bridge-setup/SKILL.md` or run:
+
+```bash
+cat "$(npm root -g)/tauri-agent-tools/.agents/skills/tauri-bridge-setup/SKILL.md"
+```