|
| 1 | +# Agent Guidelines for Pupu Project |
| 2 | + |
| 3 | +This document provides guidelines for AI agents working on the Pupu codebase. It covers build commands, linting, testing, code style, and project conventions. |
| 4 | + |
| 5 | +## Build Commands |
| 6 | + |
| 7 | +### Prerequisites |
| 8 | +- [Bun](https://bun.sh) (JavaScript runtime) |
| 9 | +- [Rust](https://rust-lang.org) (with `wasm32-unknown-unknown` target) |
| 10 | +- [wasm-pack](https://rustwasm.github.io/wasm-pack/) |
| 11 | +- [Tauri prerequisites](https://v2.tauri.app/start/prerequisites) |
| 12 | +- [uv](https://docs.astral.sh/uv/) (Python tool) |
| 13 | +- [Android SDK](https://developer.android.com/studio) (for Android builds) |
| 14 | + |
| 15 | +### Initialization |
| 16 | +```bash |
| 17 | +bun run install:pre # Build WASM endpoint |
| 18 | +bun install # Install npm dependencies |
| 19 | +bun run install:post # Generate icons, IPC bindings, database schema, install Playwright |
| 20 | +``` |
| 21 | + |
| 22 | +### Development |
| 23 | +```bash |
| 24 | +# Web development |
| 25 | +bun run dev |
| 26 | + |
| 27 | +# Native desktop development (Tauri) |
| 28 | +bun run native:dev |
| 29 | + |
| 30 | +# Android development |
| 31 | +bun run android:dev |
| 32 | +``` |
| 33 | + |
| 34 | +### Production Builds |
| 35 | +```bash |
| 36 | +# Web |
| 37 | +bun run build |
| 38 | + |
| 39 | +# Native desktop |
| 40 | +bun run native:build |
| 41 | + |
| 42 | +# Android APK |
| 43 | +bun run android:build |
| 44 | +``` |
| 45 | + |
| 46 | +### Web Preview |
| 47 | +```bash |
| 48 | +bun run preview # Runs wrangler dev on Cloudflare Workers |
| 49 | +``` |
| 50 | + |
| 51 | +### WASM Build |
| 52 | +```bash |
| 53 | +bun run wasm:build |
| 54 | +``` |
| 55 | + |
| 56 | +## Linting and Testing |
| 57 | + |
| 58 | +### TypeScript/JavaScript |
| 59 | +```bash |
| 60 | +# Type checking and ESLint |
| 61 | +bun run check |
| 62 | + |
| 63 | +# Run Playwright end‑to‑end tests |
| 64 | +bun run test |
| 65 | + |
| 66 | +# Run a single Playwright test file |
| 67 | +bun run test tests/auth.test.ts |
| 68 | + |
| 69 | +# Run tests matching a title pattern |
| 70 | +bun run test -- --grep "登录表单验证" |
| 71 | +``` |
| 72 | + |
| 73 | +### Rust |
| 74 | +```bash |
| 75 | +# Format check |
| 76 | +cargo fmt --check |
| 77 | + |
| 78 | +# Linting with Clippy |
| 79 | +cargo clippy --workspace |
| 80 | + |
| 81 | +# Run all Rust unit tests |
| 82 | +cargo test --workspace |
| 83 | + |
| 84 | +# Run tests for a specific crate |
| 85 | +cargo test -p utils |
| 86 | + |
| 87 | +# Build in release mode |
| 88 | +cargo build --release |
| 89 | +``` |
| 90 | + |
| 91 | +## Code Style Guidelines |
| 92 | + |
| 93 | +### Naming Conventions |
| 94 | +- **Functions and variables**: `snake_case` (applies to both Rust and TypeScript) |
| 95 | +- **Class names**: `PascalCase` |
| 96 | +- **Interface/trait names**: `PascalCase` |
| 97 | +- **Module names**: `snake_case` |
| 98 | +- **Constants**: `SCREAMING_SNAKE_CASE` |
| 99 | +- **Type parameters**: `T`, `U`, `V` or descriptive camelCase (`TResult`) |
| 100 | + |
| 101 | +### TypeScript / SolidJS |
| 102 | +- Use strict TypeScript (`strict: true` in tsconfig.json) |
| 103 | +- No unused locals or parameters (`noUnusedLocals`, `noUnusedParameters`) |
| 104 | +- Use `type` imports for type‑only imports: |
| 105 | + ```ts |
| 106 | + import type { Person } from "~/lib/types"; |
| 107 | + import { createSignal } from "solid‑js"; |
| 108 | + ``` |
| 109 | +- Prefer `async`/`await` over raw promises |
| 110 | +- Use `Uint8Array` for binary data |
| 111 | +- Use `bigint` for large integers (matching Rust `i64`/`u64`) |
| 112 | +- Use `snake_case` for method names and properties (matching Rust IPC) |
| 113 | +- Class methods that return promises should be marked `async` |
| 114 | +- Use SolidJS reactive primitives (`createSignal`, `createEffect`, `createMemo`) |
| 115 | + |
| 116 | +### Rust |
| 117 | +- Edition 2024 |
| 118 | +- Use `eyre::Result` for internal error handling |
| 119 | +- Convert to `Result<T, String>` for IPC via the `.mse()` extension |
| 120 | +- Use `serde_json::Value` for JSON values crossing the IPC boundary |
| 121 | +- Derive `Serialize`/`Deserialize` with `serde` for IPC types |
| 122 | +- Use `taurpc` procedural macros for defining IPC endpoints |
| 123 | +- Use `#[derive(Default)]` where appropriate |
| 124 | +- Use `Arc<Slab<...>>` for handle‑based resource pools |
| 125 | +- Use `tokio` for async runtime |
| 126 | + |
| 127 | +### Imports Organization |
| 128 | +1. Standard library / external crates |
| 129 | +2. Internal modules |
| 130 | +3. Type‑only imports |
| 131 | +4. Relative imports |
| 132 | + |
| 133 | +Example: |
| 134 | +```rust |
| 135 | +use std::sync::Arc; |
| 136 | +use eyre::eyre; |
| 137 | +use tauri::{Runtime, Window}; |
| 138 | +use crate::error::MapStringError; |
| 139 | +``` |
| 140 | + |
| 141 | +### Error Handling |
| 142 | +- **Rust**: Use `eyre::Result` and `eyre!` macro for internal errors. Convert to `String` with `.mse()` when returning over IPC. |
| 143 | +- **TypeScript**: Use `try`/`catch` with `async` functions. Throw `Error` objects. |
| 144 | +- **Playwright tests**: Use `expect` assertions; failures are reported as test failures. |
| 145 | + |
| 146 | +### Project Structure |
| 147 | +``` |
| 148 | +pupu/ |
| 149 | +├── Cargo.toml (workspace) |
| 150 | +├── package.json |
| 151 | +├── src/ (TypeScript frontend – SolidJS) |
| 152 | +├── native/ (Tauri backend) |
| 153 | +├── wasm/endpoint/ (Rust WebAssembly) |
| 154 | +├── crates/ (shared Rust libraries) |
| 155 | +├── cli/ (standalone relay binary) |
| 156 | +├── tests/ (Playwright end‑to‑end tests) |
| 157 | +├── public/ (static assets) |
| 158 | +├── scripts/ (Python utilities) |
| 159 | +└── docs/ (project documentation) |
| 160 | +``` |
| 161 | + |
| 162 | +### Commit Messages |
| 163 | +Follow [Conventional Commits](https://www.conventionalcommits.org/): |
| 164 | +- `fix:` for bug fixes |
| 165 | +- `feat:` for new features |
| 166 | +- `docs:` for documentation changes |
| 167 | +- `chore:` for maintenance tasks |
| 168 | + |
| 169 | +### Key Technologies |
| 170 | +- **Database**: Prisma for schema definition, Kysely for type‑safe SQL queries, SQLite via `tokio‑rusqlite` |
| 171 | +- **IPC**: Tauri‑RPC with `#[taurpc::procedures]` traits, `#[taurpc::resolvers]` implementations, TypeScript bindings via `export_config` |
| 172 | +- **WebAssembly**: Built with `wasm‑pack`, imported as `@pupu/endpoint`, functions exposed via `#[wasm_bindgen]` |
| 173 | +- **Android**: Keystore in `keystore.properties`, build with `tauri android build`, icons from `public/icon.svg` |
| 174 | + |
| 175 | + |
| 176 | + |
| 177 | +### Editor / Tooling |
| 178 | +- No Cursor rules (`.cursorrules`) or Copilot instructions (`.github/copilot-instructions.md`) are present. |
| 179 | + |
| 180 | +## Quick Reference |
| 181 | +| Task | Command | |
| 182 | +|------|---------| |
| 183 | +| Type check | `bun run check` | |
| 184 | +| Run all tests | `bun run test` & `cargo test --workspace` | |
| 185 | +| Lint Rust | `cargo clippy --workspace` | |
| 186 | +| Format Rust | `cargo fmt` | |
| 187 | +| Start web dev | `bun run dev` | |
| 188 | +| Start native dev | `bun run native:dev` | |
| 189 | +| Build web | `bun run build` | |
| 190 | +| Build native | `bun run native:build` | |
| 191 | +| Build Android | `bun run android:build` | |
0 commit comments