mcp-subagents-opencode 1.0.0

package/build/templates/overlays/coder-tauri.mdx

@@ -0,0 +1,566 @@
+## TAURI 2.x GUIDELINES
+
+You are working in a **Tauri 2.x** desktop application codebase (Rust backend + web frontend). Apply these patterns with zero exceptions. This is Tauri v2 -- do NOT use Tauri v1 APIs.
+
+### Project Structure -- THE STANDARD LAYOUT
+```
+my-app/
+  src/                        # Frontend (React/Vue/Svelte/etc.)
+  src-tauri/
+    Cargo.toml                # Rust deps -- tauri, serde, thiserror
+    tauri.conf.json           # App config, bundle ID, plugins, security
+    capabilities/             # ACL capability files (JSON/TOML)
+      default.json            # Auto-enabled permissions for windows
+    icons/                    # App icons (output of `tauri icon`)
+    build.rs                  # Must call tauri_build::build()
+    src/
+      lib.rs                  # Main entry -- Builder, plugins, state, commands
+      main.rs                 # Desktop-only: just calls app_lib::run()
+      commands/               # Split commands into modules by domain
+        mod.rs
+        files.rs
+        settings.rs
+      state.rs                # AppState structs + type aliases
+      errors.rs               # Custom error types with thiserror + Serialize
+```
+
+- **lib.rs is the real entry point** -- `main.rs` only calls `app_lib::run()`. This enables mobile support.
+- **NEVER put all commands in lib.rs** for non-trivial apps. Use a `commands/` module.
+- Cargo.toml must include `[lib]` section with `name = "app_lib"` and `crate-type = ["staticlib", "cdylib", "rlib"]` for mobile compatibility.
+
+### lib.rs Entry Point Pattern
+```rust
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_fs::init())
+        .plugin(tauri_plugin_shell::init())
+        .manage(std::sync::Mutex::new(AppState::default()))
+        .invoke_handler(tauri::generate_handler![
+            commands::files::read_project,
+            commands::files::save_project,
+            commands::settings::get_settings,
+            commands::settings::update_settings,
+        ])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+### Commands -- #[tauri::command]
+
+**Basic command with arguments:**
+```rust
+#[tauri::command]
+fn greet(name: String) -> String {
+    format!("Hello, {}!", name)
+}
+```
+
+**Frontend invocation -- arguments are camelCase by default:**
+```typescript
+import { invoke } from '@tauri-apps/api/core';
+const result = await invoke<string>('greet', { name: 'World' });
+```
+
+**Force snake_case arguments from frontend:**
+```rust
+#[tauri::command(rename_all = "snake_case")]
+fn process_data(file_path: String) -> Result<(), AppError> { ... }
+```
+
+**Async commands -- MUST return Result:**
+```rust
+#[tauri::command]
+async fn fetch_data(url: String) -> Result<Vec<DataItem>, AppError> {
+    let response = reqwest::get(&url).await.map_err(AppError::Network)?;
+    let items = response.json().await.map_err(AppError::Parse)?;
+    Ok(items)
+}
+```
+
+**Accessing AppHandle, Window, WebviewWindow in commands:**
+```rust
+#[tauri::command]
+fn do_work(app: tauri::AppHandle, window: tauri::WebviewWindow) -> Result<(), AppError> {
+    let label = window.label();
+    // Use app for emit, state, etc.
+    Ok(())
+}
+```
+
+**Returning large binary data -- use ipc::Response to avoid JSON overhead:**
+```rust
+use tauri::ipc::Response;
+
+#[tauri::command]
+fn read_binary(path: String) -> Result<Response, AppError> {
+    let data = std::fs::read(&path).map_err(AppError::Io)?;
+    Ok(Response::new(data))
+}
+```
+
+### Error Handling -- THE MANDATORY PATTERN
+
+Standard Rust errors do NOT implement `serde::Serialize`. You MUST create a custom error type.
+
+```rust
+// src-tauri/src/errors.rs
+#[derive(Debug, thiserror::Error)]
+pub enum AppError {
+    #[error(transparent)]
+    Io(#[from] std::io::Error),
+
+    #[error("Database error: {0}")]
+    Database(String),
+
+    #[error("Not found: {0}")]
+    NotFound(String),
+
+    #[error("Validation failed: {0}")]
+    Validation(String),
+
+    #[error(transparent)]
+    Anyhow(#[from] anyhow::Error),
+}
+
+// REQUIRED: Manual Serialize impl -- derive won't work for error types
+impl serde::Serialize for AppError {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where S: serde::ser::Serializer {
+        serializer.serialize_str(self.to_string().as_ref())
+    }
+}
+```
+
+- Add `thiserror = "2"` and `serde = { version = "1", features = ["derive"] }` to Cargo.toml.
+- Use `#[from]` for automatic conversion with `?` operator.
+- NEVER use `Result<T, String>` in production -- always use a typed error enum.
+
+### State Management -- Mutex Patterns
+
+**Setup state:**
+```rust
+use std::sync::Mutex;
+
+#[derive(Default)]
+struct AppState {
+    counter: u32,
+    config: Option<Config>,
+}
+
+// Type alias prevents State<'_, Mutex<AppState>> vs State<'_, AppState> runtime panics
+type AppStateMutex = Mutex<AppState>;
+
+// In lib.rs run():
+.manage(Mutex::new(AppState::default()))
+```
+
+**Access state in commands:**
+```rust
+#[tauri::command]
+fn increment(state: tauri::State<'_, AppStateMutex>) -> Result<u32, AppError> {
+    let mut s = state.lock().map_err(|_| AppError::Validation("poisoned lock".into()))?;
+    s.counter += 1;
+    Ok(s.counter)
+}
+```
+
+**Async commands with state -- use tokio Mutex if holding lock across .await:**
+```rust
+use tauri::async_runtime::Mutex as AsyncMutex;
+
+#[tauri::command]
+async fn load_data(state: tauri::State<'_, AsyncMutex<AppState>>) -> Result<String, AppError> {
+    let mut s = state.lock().await;
+    s.config = Some(fetch_config().await?);
+    Ok("loaded".into())
+}
+```
+
+**Access state outside commands via AppHandle:**
+```rust
+fn background_task(app: tauri::AppHandle) {
+    let state = app.state::<AppStateMutex>();
+    let mut s = state.lock().unwrap();
+    s.counter = 0;
+}
+```
+
+- You do NOT need `Arc` for Tauri managed state -- Tauri wraps it in `Arc` internally.
+- Each state type must be unique. You cannot `.manage()` two values of the same type.
+- Use `std::sync::Mutex` by default. Only use `tauri::async_runtime::Mutex` when you hold the lock across `.await` points.
+
+### Events -- Rust to Frontend Communication
+
+**Emit global event from Rust:**
+```rust
+use tauri::Emitter;
+
+#[tauri::command]
+fn start_sync(app: tauri::AppHandle) {
+    std::thread::spawn(move || {
+        for progress in 0..=100 {
+            app.emit("sync-progress", progress).unwrap();
+            std::thread::sleep(std::time::Duration::from_millis(50));
+        }
+        app.emit("sync-complete", ()).unwrap();
+    });
+}
+```
+
+**Listen in frontend:**
+```typescript
+import { listen } from '@tauri-apps/api/event';
+
+const unlisten = await listen<number>('sync-progress', (event) => {
+    console.log(`Progress: ${event.payload}%`);
+});
+
+// ALWAYS unlisten on cleanup (React useEffect return, Vue onUnmounted, etc.)
+unlisten();
+```
+
+**Emit to specific window:**
+```rust
+use tauri::Emitter;
+app.emit_to("settings", "config-changed", &new_config).unwrap();
+```
+
+**Emit with filter:**
+```rust
+use tauri::{Emitter, EventTarget};
+app.emit_filter("file-opened", &path, |target| match target {
+    EventTarget::WebviewWindow { label } => label == "main" || label == "editor",
+    _ => false,
+}).unwrap();
+```
+
+### Channels -- For Streaming / High-Throughput Data
+
+Use channels instead of events when you need ordered, fast streaming (download progress, log tailing, etc.).
+
+**Rust side:**
+```rust
+use tauri::ipc::Channel;
+use serde::Serialize;
+
+#[derive(Clone, Serialize)]
+#[serde(rename_all = "camelCase", tag = "event", content = "data")]
+enum DownloadEvent {
+    #[serde(rename_all = "camelCase")]
+    Progress { download_id: usize, bytes_done: usize, total: usize },
+    #[serde(rename_all = "camelCase")]
+    Finished { download_id: usize },
+}
+
+#[tauri::command]
+async fn download(url: String, on_event: Channel<DownloadEvent>) -> Result<(), AppError> {
+    // ... stream data ...
+    on_event.send(DownloadEvent::Progress { download_id: 1, bytes_done: 500, total: 1000 })?;
+    on_event.send(DownloadEvent::Finished { download_id: 1 })?;
+    Ok(())
+}
+```
+
+**Frontend side:**
+```typescript
+import { invoke, Channel } from '@tauri-apps/api/core';
+
+type DownloadEvent =
+    | { event: 'progress'; data: { downloadId: number; bytesDone: number; total: number } }
+    | { event: 'finished'; data: { downloadId: number } };
+
+const onEvent = new Channel<DownloadEvent>();
+onEvent.onmessage = (msg) => {
+    if (msg.event === 'progress') {
+        updateProgressBar(msg.data.bytesDone / msg.data.total);
+    }
+};
+await invoke('download', { url: 'https://example.com/file.bin', onEvent });
+```
+
+- Channels are faster than events and guarantee message ordering.
+- Events are for pub/sub (multi-consumer). Channels are for point-to-point streaming.
+
+### Capabilities & Permissions -- Tauri 2.x Security (Replaces v1 Allowlist)
+
+Capabilities are JSON files in `src-tauri/capabilities/`. All files in this directory are auto-enabled.
+
+**src-tauri/capabilities/default.json:**
+```json
+{
+    "$schema": "../gen/schemas/desktop-schema.json",
+    "identifier": "default",
+    "description": "Default capability for the main window",
+    "windows": ["main"],
+    "permissions": [
+        "core:default",
+        "fs:default",
+        "fs:allow-read-text-file",
+        "fs:allow-write-text-file",
+        "shell:allow-open",
+        {
+            "identifier": "fs:scope",
+            "allow": [{ "path": "$APPDATA" }, { "path": "$APPDATA/**" }]
+        }
+    ]
+}
+```
+
+**Platform-specific capabilities:**
+```json
+{
+    "identifier": "desktop-only",
+    "windows": ["main"],
+    "platforms": ["linux", "macOS", "windows"],
+    "permissions": ["global-shortcut:allow-register"]
+}
+```
+
+**Multi-window with different capabilities:**
+```json
+{
+    "identifier": "settings-window",
+    "windows": ["settings"],
+    "permissions": ["core:default", "fs:allow-read-text-file"]
+}
+```
+
+- A window with NO matching capability has ZERO access to IPC. This is intentional.
+- Permission format: `plugin-name:permission-name` (e.g., `fs:allow-read-text-file`).
+- Core permissions are prefixed with `core:` (e.g., `core:window:allow-set-title`).
+- Deny scopes take precedence over allow scopes.
+- NEVER use `"windows": ["*"]` unless every window truly needs those permissions.
+
+### Plugin System
+
+**Using official plugins:**
+```bash
+# Install from npm + cargo in one step
+npm run tauri add fs
+npm run tauri add shell
+npm run tauri add updater
+```
+
+**Register in lib.rs:**
+```rust
+tauri::Builder::default()
+    .plugin(tauri_plugin_fs::init())
+    .plugin(tauri_plugin_shell::init())
+    .plugin(tauri_plugin_updater::init())
+```
+
+**Creating a custom plugin:**
+```rust
+use tauri::plugin::{Builder as PluginBuilder, TauriPlugin};
+use tauri::Runtime;
+
+#[tauri::command]
+fn my_plugin_command(state: tauri::State<'_, MyPluginState>) -> Result<String, AppError> {
+    Ok("plugin response".into())
+}
+
+pub fn init<R: Runtime>() -> TauriPlugin<R> {
+    PluginBuilder::new("my-plugin")
+        .setup(|app, _api| {
+            app.manage(MyPluginState::default());
+            Ok(())
+        })
+        .invoke_handler(tauri::generate_handler![my_plugin_command])
+        .on_navigation(|window, url| {
+            // Return false to block navigation
+            true
+        })
+        .on_event(|app, event| {
+            // Handle app lifecycle events
+        })
+        .build()
+}
+```
+
+**Frontend calls plugin commands with namespace prefix:**
+```typescript
+await invoke('plugin:my-plugin|my_plugin_command');
+```
+
+- Plugin commands require permissions in capabilities: `"my-plugin:allow-my-plugin-command"`.
+- For inline plugins (defined in the app, not a crate), you must update `build.rs` to generate permissions.
+
+### Window Management
+
+**Create windows from Rust:**
+```rust
+use tauri::{WebviewWindowBuilder, WebviewUrl};
+
+#[tauri::command]
+fn open_settings(app: tauri::AppHandle) -> Result<(), AppError> {
+    let _window = WebviewWindowBuilder::new(&app, "settings", WebviewUrl::App("/settings".into()))
+        .title("Settings")
+        .inner_size(600.0, 400.0)
+        .build()
+        .map_err(|e| AppError::Validation(e.to_string()))?;
+    Ok(())
+}
+```
+
+**Create windows from frontend (requires capability):**
+```typescript
+import { WebviewWindow } from '@tauri-apps/api/webviewWindow';
+
+const settings = new WebviewWindow('settings', {
+    url: '/settings',
+    width: 600,
+    height: 400,
+    title: 'Settings',
+});
+
+settings.once('tauri://created', () => { /* success */ });
+settings.once('tauri://error', (e) => { /* handle error */ });
+```
+
+- Requires `"core:webview:allow-create-webview-window"` permission.
+- Inter-window communication: use `emit_to()` targeting window labels or global events.
+- Use `WebviewWindow::getByLabel('label')` to get a handle to an existing window.
+
+### File System Plugin
+
+**Frontend file operations:**
+```typescript
+import { readTextFile, writeTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
+import { appDataDir, join } from '@tauri-apps/api/path';
+
+// Read from app data
+const config = await readTextFile('config.json', { baseDir: BaseDirectory.AppData });
+
+// Write to app data
+await writeTextFile('config.json', JSON.stringify(settings), {
+    baseDir: BaseDirectory.AppData,
+});
+
+// Resolve absolute path
+const dataDir = await appDataDir();
+const filePath = await join(dataDir, 'projects', 'data.json');
+```
+
+**Rust path resolution:**
+```rust
+use tauri::Manager;
+
+fn get_app_data(app: &tauri::AppHandle) -> Result<std::path::PathBuf, AppError> {
+    app.path().app_data_dir().map_err(|e| AppError::Io(e.into()))
+}
+```
+
+- Paths using this API cannot traverse parent directories (`../` is blocked).
+- BaseDirectory variables for scopes: `$APPDATA`, `$APPCONFIG`, `$APPLOG`, `$HOME`, `$RESOURCE`, `$TEMP`.
+- App directories must be created at runtime before use -- they do not exist by default.
+
+### Security -- CSP & IPC Safety
+
+**tauri.conf.json CSP configuration:**
+```json
+{
+    "app": {
+        "security": {
+            "csp": {
+                "default-src": "'self' customprotocol: asset:",
+                "connect-src": "ipc: http://ipc.localhost",
+                "img-src": "'self' asset: http://asset.localhost blob: data:",
+                "style-src": "'unsafe-inline' 'self'"
+            }
+        }
+    }
+}
+```
+
+- Tauri auto-injects nonces and hashes for bundled scripts/styles at compile time.
+- NEVER use `'unsafe-eval'` unless using WASM (then use `'wasm-unsafe-eval'`).
+- Avoid loading remote scripts. Any untrusted content is an attack vector.
+- Sanitize ALL user input on the Rust side before processing.
+- Defer business logic to Rust -- minimize logic in the frontend.
+- Consider the Isolation pattern (`"isolation": { "pattern": "..." }`) for apps handling untrusted content.
+
+### Build & Distribution
+
+**Development:**
+```bash
+npm run tauri dev          # Hot-reload development
+npm run tauri build        # Production build
+npm run tauri icon          # Generate icons from source image
+```
+
+**tauri.conf.json essentials:**
+```json
+{
+    "productName": "My App",
+    "mainBinaryName": "my-app",
+    "version": "1.0.0",
+    "identifier": "com.mycompany.myapp",
+    "build": {
+        "frontendDist": "../dist",
+        "devUrl": "http://localhost:5173",
+        "beforeBuildCommand": "npm run build",
+        "beforeDevCommand": "npm run dev"
+    }
+}
+```
+
+**Updater setup (tauri.conf.json):**
+```json
+{
+    "plugins": {
+        "updater": {
+            "endpoints": ["https://releases.example.com/{{target}}/{{arch}}/{{current_version}}"],
+            "pubkey": "YOUR_PUBLIC_KEY_HERE"
+        }
+    }
+}
+```
+
+**GitHub Actions CI/CD:**
+```yaml
+- uses: tauri-apps/tauri-action@v0
+  env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+      TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+  with:
+      tagName: v__VERSION__
+      releaseName: 'v__VERSION__'
+      includeUpdaterJson: true
+```
+
+- `TAURI_SIGNING_PRIVATE_KEY` and `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` must be set as environment variables (not .env files).
+- Generate signing keys with `npx tauri signer generate`.
+- macOS requires code signing + notarization for distribution. Set `APPLE_SIGNING_IDENTITY` env var.
+- `mainBinaryName` is REQUIRED in Tauri 2.x -- the binary is no longer auto-renamed to match `productName`.
+
+### Common Gotchas -- AVOID THESE
+
+1. **Serde serialization for errors:** Standard error types don't implement `Serialize`. You MUST create a custom error type (see Error Handling section above). This is the #1 newcomer mistake.
+
+2. **State type mismatch:** `State<'_, AppState>` vs `State<'_, Mutex<AppState>>` gives a runtime panic, not a compile error. Always use a type alias for your wrapped state.
+
+3. **Async commands with borrowed data:** `&str` and `State<'_, T>` in async commands cause "future is not Send" errors. Solution: async commands MUST return `Result<T, E>`. For `&str`, use `String` instead.
+
+4. **Missing capabilities:** Commands silently fail (or return 400) if the capability file doesn't include the permission. Check `src-tauri/capabilities/` first when a command doesn't work.
+
+5. **Frontend argument casing:** Rust `snake_case` args become `camelCase` on the frontend by default. Use `#[tauri::command(rename_all = "snake_case")]` to keep snake_case.
+
+6. **v1 imports still in code:** `@tauri-apps/api/tauri` is now `@tauri-apps/api/core`. `@tauri-apps/api/fs` is now `@tauri-apps/plugin-fs`. There is no backward compatibility.
+
+7. **Events are not type-safe:** Events use JSON payloads with no type checking at the Rust/TS boundary. Prefer commands for typed request/response and channels for typed streaming.
+
+8. **Window without capability = zero IPC access.** If a webview or its window matches no capability, it has no access to the IPC layer at all. This is not a bug.
+
+9. **Mutex poisoning:** Use `.lock().map_err(...)` instead of `.lock().unwrap()` in commands. A panicked thread poisons the mutex, and `.unwrap()` will crash subsequent calls.
+
+10. **Plugin names cannot contain underscores.** Use hyphens (`my-plugin`, not `my_plugin`). Underscore names cause cryptic serde deserialization errors in capabilities.
+
+### Naming & Conventions
+- `snake_case` for Rust functions, modules, variables
+- `PascalCase` for Rust types, traits, enums
+- `camelCase` for TypeScript functions, variables, and invoke argument names
+- Commands registered with `generate_handler!` use their Rust function name as the invoke name
+- Plugin commands are invoked as `plugin:plugin-name|command_name`