|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +Project agent guidelines for Snipp (Rust + Tauri + React). |
| 4 | + |
| 5 | +## Git |
| 6 | +- Use `git commit -S -m` for all commits (fish alias: `gc`). Commits must be GPG-signed. |
| 7 | +- Do NOT add co-author trailers, Amp thread IDs, or any agent metadata to commit messages. |
| 8 | + |
| 9 | +## GitHub |
| 10 | +- Always use the `gh` CLI to fetch issues, PRs, and other GitHub data (e.g. `gh issue view 7`). Do not scrape via `read_web_page`. |
| 11 | + |
| 12 | +## General |
| 13 | +- Prefer small, focused changes; keep diffs readable and reversible. |
| 14 | +- Keep command names and event names consistent across Rust and TypeScript. |
| 15 | +- Avoid hard-coded shortcuts, paths, and feature flags; read from config. |
| 16 | +- Keep UI logs behind a debug flag; avoid console noise in production builds. |
| 17 | +- Use ASCII-only content unless the file already uses Unicode. |
| 18 | + |
| 19 | +## Rust |
| 20 | +- Use `Result<T, E>` with clear error messages; avoid `unwrap` and `expect` outside tests. |
| 21 | +- Favor `thiserror` or custom error enums for command failures and IO issues. |
| 22 | +- Keep Tauri commands thin; move logic into helper modules for testability. |
| 23 | +- Avoid blocking the async runtime; offload heavy work to threads. |
| 24 | +- Keep macOS-only code behind `#[cfg(target_os = "macos")]`. |
| 25 | +- For file IO, validate paths and create directories safely. |
| 26 | + |
| 27 | +## Tauri |
| 28 | +- Match every Rust command in `invoke_handler` with a TS definition and UI usage. |
| 29 | +- When updating global shortcuts, unregister previous bindings before re-registering. |
| 30 | +- Keep window creation centralized; enforce single-instance for popup/editor/preferences. |
| 31 | +- Prefer Tauri APIs over shell commands when possible. |
| 32 | +- Use the clipboard plugin or platform APIs for image data, not AppleScript when feasible. |
| 33 | + |
| 34 | +## React/TypeScript |
| 35 | +- Keep hooks side-effect free; isolate Tauri calls in hooks or services. |
| 36 | +- Treat event payloads as typed data; validate or narrow before use. |
| 37 | +- Ensure editor state updates are idempotent and resilient to out-of-order events. |
| 38 | +- Avoid global listeners without cleanup; always unregister on unmount. |
| 39 | + |
| 40 | +## Testing & QA |
| 41 | +- Cover config schema migration with tests. |
| 42 | +- Add manual verification steps for capture -> popup -> editor flows. |
| 43 | +- Validate on Retina and external displays with different scale factors. |
| 44 | +- Verify OCR output, clipboard results, and hotkey registration after preferences changes. |
| 45 | + |
| 46 | +## Learnings |
| 47 | + |
| 48 | +### Vite Environment Variables |
| 49 | +- **Issue #20**: `process.env` is not available in Vite browser apps. The idomatic check is `import.meta.env.DEV`. |
| 50 | +- When using `import.meta.env`, ensure `src/vite-env.d.ts` exists with `/// <reference types="vite/client" />` for proper TypeScript support. |
0 commit comments