---

name: add-tauri-command description: Use when adding, renaming, or changing the signature of a Tauri command in src-tauri — any new IPC surface between the Rust core and the React UI.

Add a Tauri command

End-to-end checklist. A command is not "done" until both sides are typed and tested.

Checklist (todo per item)

1. Domain module. Add the command to src-tauri/src/commands/<domain>.rs (create the domain file if new — never a catch-all module). Name: snake_case verb phrase, one command per user-facing action.
2. Signature. async fn if it does I/O; owned params; State<'_, AppState> for state; Channel<T> param if it streams. Returns Result<T, Error> (the app error enum — add a variant if no existing one fits; wrap engine errors via #[from]).
3. Thin shell. Body = unwrap args → call engine / db/ repository / jobs layer → map errors. If you're writing SQL or business logic inside the command, stop and move it down a layer.
4. Register. Add to the single generate_handler![...] list in lib.rs (and to tauri_specta::Builder command list). There is exactly one registration site.
5. Regenerate bindings. Run the specta export (see justfile: just bindings) so src/lib/ipc/bindings.gen.ts updates. Never hand-edit that file.
6. Typed wrapper. Expose it from src/lib/ipc/<domain>.ts re-exporting the generated function with any ergonomics (query-key helpers for TanStack Query). Feature code imports the wrapper, never the bindings file or raw invoke.
7. Tests, both sides. Rust: unit test for the layer the command delegates to (the command itself stays thin enough not to need one); if the command has branching, test it with a test AppState. TS: if a hook/component consumes it, mock via mockIPC in the colocated test.
8. Capabilities. If the command needs a plugin permission, add it to the relevant file in src-tauri/capabilities/ (per-concern files, minimum scope).
9. Gate. just check.

Common mistakes

• Registering in a second invoke_handler call — Tauri silently keeps only the last one.
• Returning String errors — the frontend loses the kind discriminant.
• Streaming via events instead of Channel<T> — events are broadcast and unordered per docs; channels are the streaming path.
• Forgetting clearMocks() in the TS test — IPC mocks leak across tests.