SAP-PLEX-SYNC/AGENTS.md

AGENTS.md

Build, Lint, and Test Commands

Backend (Rust)

cd backend && cargo build          # Build project
cd backend && cargo test           # Run all tests
cd backend && cargo test my_test   # Run test matching pattern
cd backend && cargo test -- --exact # Run exact test name
cd backend && cargo test -- --test-threads=1  # Run tests sequentially
cd backend && cargo test -- --nocapture  # Show test output
cd backend && cargo test --lib     # Library tests only
cd backend && cargo fmt            # Format code
cd backend && cargo fmt --check    # Check formatting
cd backend && cargo clippy         # Lint code

Frontend (React + TypeScript)

cd frontend && npm install          # Install dependencies
cd frontend && npm run dev          # Start dev server (port 3000)
cd frontend && npm run build        # Build for production (tsc + vite)
cd frontend && npm run lint         # Lint with ESLint
cd frontend && npx tsc --noEmit     # Type check only
cd frontend && npm test             # Run Jest tests
cd frontend && npm run test:watch   # Run tests in watch mode

Docker

docker-compose up -d               # Start all services
docker-compose logs -f backend     # View backend logs
docker-compose logs -f frontend    # View frontend build/logs
docker-compose down                # Stop all services
docker cp frontend/dist/. sap-sync-frontend:/usr/share/nginx/html/  # Update frontend in container
docker exec sap-sync-frontend nginx -s reload  # Reload nginx

Code Style Guidelines

Rust Backend

Imports — Alphabetical order, grouped with blank lines: std → external → local. Use full paths: crate::handlers::sync. Avoid wildcard imports.

Naming — Types: PascalCase. Functions: snake_case. Constants: SCREAMING_SNAKE_CASE. Modules: snake_case.

Error Handling — Use thiserror::Error for typed errors. Use ApiError in HTTP handlers. Log with tracing::{info, error} macros. Never use unwrap(); prefer ?, match, or unwrap_or_else(). Convert errors to String for ApiError::Database.

Types — i32 for DB IDs, f64 for decimals. String for owned text, &str for borrowed. Option<T> for nullable, Vec<T> for collections. Arc<T> for shared state.

Handlers — Return impl IntoResponse. Use build_response() helper for consistent JSON responses. Extract DB connections via state.pool.get() with error handling.

Database — Use r2d2 connection pooling. Parameterized queries ($1, $2). Always handle pool errors.

React Frontend

Imports — Alphabetical, grouped: external → lib → components → pages. Named imports preferred.

Formatting — 2-space indent, single quotes, no semicolons, 100-char line limit (Prettier).

Naming — Components: PascalCase. Hooks: useCamelCase. Variables: camelCase.

TypeScript — Strict mode enabled. Avoid any; use unknown or generics. Define interfaces for API responses. Prefer type over interface for unions.

Error Handling — Use try/catch for async ops. Log with logger.error(). Show user feedback via toast.success()/toast.error(). Use MUI Dialogs for confirmations, not window.confirm.

Components — Functional components with hooks. useCallback for handlers, useMemo for expensive calcs. Avoid inline functions in JSX props.

Project Structure

SAP-PLEX-SYNC/
├── backend/src/
│   ├── lib.rs              # Library exports
│   ├── main.rs             # Entry point (rouille HTTP server)
│   ├── handlers_sync.rs    # Sync API handlers (axum - not currently used)
│   ├── handlers.rs         # Other HTTP handlers (legacy)
│   ├── models.rs           # Data models
│   ├── state.rs            # AppState (r2d2 pool)
│   ├── errors.rs           # ApiError enum
│   ├── response.rs         # Response helpers
│   ├── sync.rs             # Sync types & structs
│   ├── plesk_client.rs     # Plesk API client
│   ├── sap_client.rs       # SAP API client
│   ├── config.rs           # Configuration
│   └── ...
├── frontend/src/
│   ├── pages/              # Page components
│   ├── components/         # Reusable components
│   ├── lib/api.ts          # API client (apiJson)
│   ├── lib/hooks.ts        # usePolling, formatDate
│   ├── lib/logger.ts       # Logging utility
│   └── contexts/           # React contexts
├── database/               # Migrations and seeds
└── docker-compose.yml

Cursor Rules (.cursorrules)

• Follow cargo fmt and cargo clippy before committing
• Use anyhow::Result for error propagation, ApiError for HTTP
• Return impl IntoResponse for axum handlers (note: main server uses rouille)
• Functional components with hooks; avoid inline JSX functions
• Use useCallback/useMemo for performance
• Test user interactions with React Testing Library, not implementation details
• Always check for unsafe unwrap() calls and replace with proper error handling
• Use proper logging instead of console.log in frontend
• Keep functions small and focused
• Use meaningful variable and function names
• Add comments for complex logic

API Response Format

Backend returns flat JSON (no data wrapper):

{ "is_running": false, "stats": { "running": 0 }, "jobs": [...] }

For server listings, returns direct array: [{ "id": 1, "name": "test", ... }]

Frontend uses apiJson<T>() from lib/api.ts for typed API calls. Frontend proxy: /api → http://localhost:3001 (configured in vite.config.ts).

Testing

Backend — Tests in #[cfg(test)] mod tests blocks. Use #[test] for sync, #[tokio::test] for async. Test both happy paths and error cases. Mock external deps with mockall.

To run a specific test: cd backend && cargo test test_function_name -- --exact To run tests matching a pattern: cd backend && cargo test pattern_name To run tests sequentially: cd backend && cargo test -- --test-threads=1 To see test output: cd backend && cargo test -- --nocapture

Frontend — Jest + React Testing Library. Use screen.getByRole/getByText. Test user interactions, not implementation. Mock API with jest.mock().

To run frontend tests: cd frontend && npm test To run tests in watch mode: cd frontend && npm run test:watch

Git Workflow

Commits: type(scope): description (e.g., fix(handlers): resolve API mismatch). Types: feat, fix, docs, refactor, chore. Branches: feature/, bugfix/, hotfix/.

Key Reminders

1. Build and lint before committing: cargo build --lib, cargo fmt, cargo clippy, npm run build
2. Update Docker container after frontend changes: docker cp frontend/dist/. sap-sync-frontend:/usr/share/nginx/html/
3. Test API endpoints with curl http://localhost/api/... to verify response format
4. Use tracing::{info, error} for backend logging, logger.error() for frontend
5. Never use unwrap() in production code; use ? or proper error handling
6. Avoid any in TypeScript; use unknown or proper types
7. Use MUI Dialogs for confirmations, not window.confirm
8. Use toast.success()/toast.error() for user feedback, not alert()
9. Remember that the main HTTP server uses rouille (not axum) in main.rs
10. Database column for passwords is named password_hash, not password