|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file gives automated agents concise guidance for working in this repository. |
| 4 | + |
| 5 | +## Overview |
| 6 | +This is a polyglot monorepo: |
| 7 | +- Rust crates under `crates/` and `plugins/` plus some standalone dirs. |
| 8 | +- Tauri / desktop and web apps under `apps/`. |
| 9 | +- Shared TypeScript packages under `packages/`. |
| 10 | +- Scripts (Python, shell, Swift) under `scripts/`. |
| 11 | + |
| 12 | +## Build |
| 13 | +- Rust: `cargo build` for whole workspace; `cargo build -p <crate>` for a single crate. |
| 14 | +- Use feature flags to avoid heavy ML deps: e.g. `cargo test -p tauri-plugin-listener --no-default-features --features export-types` for specta export without local LLM/STT. |
| 15 | +- Prefer optional dependencies + a dedicated feature (e.g. `connector`) instead of unconditional linking. |
| 16 | +- Node/TS: `pnpm install`, then `pnpm run build` (Turbo orchestrates). For a single package: `pnpm --filter <name> run build`. |
| 17 | + |
| 18 | +## Testing |
| 19 | +- Rust: `cargo test` (workspace). Single crate: `cargo test -p <crate>`. With feature gating: `cargo test -p <crate> --no-default-features --features <feat>`. |
| 20 | +- Run a single Rust test: `cargo test -p <crate> <test_name>`. |
| 21 | +- TypeScript/Vitest: `pnpm --filter <pkg> test`. Single test name: `pnpm --filter <pkg> vitest run path/to/file.test.ts -t "test name"`. |
| 22 | +- Run snapshot tests: `cargo install cargo-insta` then `cargo test`. |
| 23 | + |
| 24 | +## Formatting & Lint |
| 25 | +- Rust formatting via `dprint fmt` (uses exec rustfmt). Run before committing. |
| 26 | +- Keep Rust imports grouped: std, external crates, workspace crates, local modules. |
| 27 | +- TypeScript formatting also via `dprint fmt`. Do not introduce other formatters unless necessary. |
| 28 | +- Avoid trailing whitespace; keep line length reasonable (<120 typical). |
| 29 | + |
| 30 | +## i18n / Translations |
| 31 | +- Uses Lingui for internationalization. After modifying UI text, run: `task i18n` (or `pnpm -F desktop lingui:extract`). |
| 32 | +- **CRITICAL**: Always run `pnpm -F desktop lingui:compile` after extract and before building to sync translation keys. |
| 33 | +- Build order for desktop: `poetry run python scripts/pre_build.py` → `pnpm -F desktop lingui:compile` → `pnpm -F ui build` → `pnpm -F desktop tauri build`. |
| 34 | +- Translation catalogs: `apps/desktop/src/locales/{en,ko}/messages.{po,ts}`. The `.ts` files are compiled from `.po`. |
| 35 | + |
| 36 | +## Conventions (Rust) |
| 37 | +- Modules & functions: `snake_case`; types & enums: `CamelCase`. |
| 38 | +- Errors: use `thiserror`; prefer a central `Error` enum and `Result<T, crate::Error>`. |
| 39 | +- Instrument async/public functions with `#[tracing::instrument(skip(...))]` when adding tracing. |
| 40 | +- Feature gating: wrap variants/APIs with `#[cfg(feature = "feat")]`; supply fallbacks when disabled. |
| 41 | + |
| 42 | +## Adding Features |
| 43 | +- Introduce new optional deps with a matching feature name; add to `default` only if broadly needed. |
| 44 | +- For specta/TS type export steps, minimize dependency surface (avoid heavy ML crates) by disabling default features. |
| 45 | +- Extend builders (e.g. event/command registration) conditionally behind feature flags. |
| 46 | + |
| 47 | +## TypeScript/Apps |
| 48 | +- Prefer explicit types for public APIs. Use consistent naming: `camelCase` for variables/functions, `PascalCase` for types/components. |
| 49 | +- Centralized config and shared utilities live in `packages/utils` and `packages/ui`. |
| 50 | +- Desktop app: `pnpm -F desktop tauri:dev` for development. Uses Vite + React + Tauri v2. |
| 51 | + |
| 52 | +## Scripts |
| 53 | +- Python uses `poetry.lock` / `pyproject.toml`; prefer `poetry run python <script>` if dependencies matter. |
| 54 | +- Shell scripts in `scripts/` should be idempotent; do not add interactive prompts. |
| 55 | + |
| 56 | +## Performance / Heavy Deps |
| 57 | +- Whisper / Llama and STT/LLM crates are large; gate them and avoid including them in lightweight export/test commands. |
| 58 | + |
| 59 | +## Pull Requests |
| 60 | +- Keep diffs minimal and focused; explain "why" in commit/PR body. |
| 61 | +- Ensure `dprint fmt` and targeted tests pass before requesting review. |
| 62 | + |
| 63 | +## Code Review |
| 64 | +- Use `coderabbit --prompt-only` for AI-powered code analysis; let it run fully to completion. |
| 65 | +- **Always run `coderabbit --prompt-only` at the end of every task** to ensure code quality. |
| 66 | + |
| 67 | +## Do Not |
| 68 | +- Do not commit large model binaries. |
| 69 | +- Do not add new formatters or global toolchains without discussion. |
| 70 | +- Do not enable heavy features for simple type export or CI smoke tests. |
0 commit comments