victauri-plugin 0.10.0

# victauri-plugin

The main [Victauri](https://github.com/4DA-Systems/victauri) crate -- an embedded MCP server that gives AI agents full-stack control of Tauri 2.0 applications.

## Quick Start

Add the dependency:

```toml
[dependencies]
victauri-plugin = "0.10"
```

Wire it into your Tauri app:

```rust
fn main() {
    tauri::Builder::default()
        .plugin(victauri_plugin::init())
        .run(tauri::generate_context!())
        .expect("error running app");
}
```

Connect Claude Code (or any MCP client) via the `victauri bridge` stdio proxy — it discovers
the running app's port automatically and survives restarts:

```json
{ "mcpServers": { "victauri": { "command": "victauri", "args": ["bridge"] } } }
```

(The raw endpoint is `http://127.0.0.1:7373/mcp`, but a fixed `url:` hardcodes a port and can
bind the wrong app — prefer the bridge.)

## Configuration

Use `VictauriBuilder` for advanced setup:

```rust,ignore
victauri_plugin::VictauriBuilder::new()
    .port(8080)
    .auth_token("my-secret-token")
    .disable_tools(&["screenshot"])
    .add_redaction_pattern(r"\b\d{3}-\d{2}-\d{4}\b")
    .enable_redaction()
    .build()
    .expect("valid config")
```

## Cargo features

| Feature | Default | What it does |
|---|---|---|
| `sqlite` | on | `query_db` and `introspect db_health` (via rusqlite). Without it both tools return a clear "not compiled in" error. |
| `bundled-sqlite` | on | Compiles SQLite into the binary (rusqlite's `bundled`). Implies `sqlite`. |

The plugin accepts rusqlite `>=0.32, <0.41`, so cargo unifies it with your app's own rusqlite —
which means `bundled-sqlite` **also switches your app's rusqlite to the bundled SQLite**. If your
app links a system SQLite or SQLCipher, keep yours by turning the default features off and
enabling only `sqlite`:

```toml
[dependencies]
victauri-plugin = { version = "0.10", default-features = false, features = ["sqlite"] }
```

(With `default-features = false` and no `sqlite`, the plugin has no rusqlite dependency at all.)

### Tauri 3 (pre-release)

| Feature | Default | What it does |
|---|---|---|
| `tauri-v3` | off | Build against Tauri 3: Tauri 3's `initialization_script` (renamed from `js_init_script`) and the Tauri 3 permission build step. |

The plugin's `tauri` requirement spans Tauri 2 **and** Tauri 3 (`>=2.0.0, <=3.0.0-alpha.5` today —
the ceiling is the newest Tauri 3 pre-release it has been built against). `tauri` allows one copy
per build, so cargo picks whichever major your app uses. On Tauri 3, also turn on `tauri-v3`:

```toml
[dependencies]
tauri = "=3.0.0-alpha.5"
tauri-runtime-wry = "=3.0.0-alpha.5"  # Tauri 3 apps select their webview runtime
victauri-plugin = { version = "0.10", features = ["tauri-v3"] }

[build-dependencies]
tauri-build = "=3.0.0-alpha.4"  # as examples/tauri3 uses
```

`tauri-v3` must match your app's Tauri major. Without it a Tauri 3 app fails to compile
victauri-plugin with `the app links Tauri 3 — enable victauri-plugin's tauri-v3 feature`; with it
a Tauri 2 app usually fails first in its own `tauri-build` step (`failed to read plugin
permissions: … autogenerated\commands\commands.toml`), next to `the tauri-v3 feature is on, but
the app links Tauri 2 — remove tauri-v3`. Nothing else changes — same tools, same `init()` /
`VictauriBuilder`, same `victauri:default` capability.

## Tools

35 MCP tools across three layers -- webview, IPC, and Rust backend (full catalog in the [tools reference](https://4da-systems.github.io/Victauri/tools-reference.html)):

### Backend (direct Rust access, no webview needed)

| Tool | What it does |
|---|---|
| `app_info` | App config, directory paths, env vars, discovered databases, process info |
| `list_app_dir` | List files in app data/config/log/local_data directories |
| `read_app_file` | Read files from app backend directories (UTF-8 or base64) |
| `query_db` | Read-only SQLite queries with auto-discovery |
| `get_memory_stats` | Real-time OS process memory (working set, page faults) |
| `invoke_command` | Call any Tauri command directly through IPC |

### IPC Layer

| Tool | What it does |
|---|---|
| `get_registry` | List all commands with schemas from `#[inspectable]` |
| `detect_ghost_commands` | Find frontend IPC calls with no backend handler |
| `check_ipc_integrity` | Detect stuck, stale, or errored IPC calls |
| `verify_state` | Compare frontend DOM against backend state |
| `resolve_command` | Natural language to matching Tauri command |

### Webview (DOM, interactions, JS)

| Tool | What it does |
|---|---|
| **`interact`** | Click, double-click, hover, focus, scroll, select |
| **`input`** | Fill inputs, type character-by-character, press keyboard keys |
| **`inspect`** | Computed CSS, bounding boxes, element highlighting, a11y audit, performance metrics |
| **`css`** | Inject/remove debug CSS |
| `eval_js` | Execute JavaScript in the webview |
| `dom_snapshot` | Full accessibility tree with ref handles |
| `find_elements` | Search for elements by text, role, test ID, or CSS selector |
| `screenshot` | Platform-native window capture |
| `assert_semantic` | Evaluate JS expression and assert against expected value |
| `wait_for` | Poll for conditions: text appears, selector matches, IPC settles |

### App-wide

| Tool | What it does |
|---|---|
| **`window`** | Get state, list windows, manage, resize, move, set title |
| **`storage`** | Read/write localStorage, sessionStorage, cookies |
| **`navigate`** | Go to URL, go back, get history, configure dialog responses |
| **`recording`** | Start/stop sessions, checkpoints, get events, export/import |
| **`logs`** | Console, network, IPC, navigation, dialog logs |
| **`introspect`** | Command timings, coverage, contract testing, startup timing, capabilities, DB health, managed state, tasks |
| **`fault`** | Inject IPC faults: delay, error, drop, corrupt (chaos engineering) |
| **`explain`** | Natural-language narration: summary, last action, diff |
| `get_plugin_info` | Victauri config: port, enabled tools, version |
| `get_diagnostics` | Server health, compatibility warnings, tool status |

## Security

- **Localhost only** -- binds to `127.0.0.1`, never exposed to network
- **Debug-only** -- `init()` returns a no-op plugin in release builds
- **Auth on by default** -- auto-generated Bearer token (auto-discovered by clients); fixed token via builder or `VICTAURI_AUTH_TOKEN`; `.auth_disabled()` to opt out
- **Rate limiting** -- Token-bucket at 1000 req/sec (default)
- **Privacy layer** -- Command allowlists/blocklists, tool disabling, regex redaction

See the full [project README](https://github.com/4DA-Systems/victauri) for architecture details and live test results.

## Documentation

Full API docs: [docs.rs/victauri-plugin](https://docs.rs/victauri-plugin)

## License

Apache-2.0 -- see [LICENSE](../../LICENSE)

Part of [Victauri](https://github.com/4DA-Systems/victauri). Built by [4DA Systems](https://4da.ai).