Cursor rule

1---
2description: Core coding principles for async-first development and security
3globs: ["src/**/*.py"]
4alwaysApply: true
5---
6 
7# Core Coding Principles
8 
9## 1. Async-First Development
10 
11- **ALWAYS** use `async def` for functions that perform I/O operations
12- Use `await` for API calls, database queries, file operations, HTTP requests
13- Leverage `asyncio.gather()` for concurrent operations
14- Use `async with` for context managers (UniFi client, Redis connections)
15- **NEVER** use blocking synchronous calls in async contexts
16- Consider using `anyio.to_thread.run_sync()` for CPU-intensive operations
17 
18## 2. Type Safety and Validation
19 
20- **ALWAYS** provide type hints for all function parameters and return values
21- Use Pydantic models for complex input/output structures
22- Prefer explicit types over `Any` or untyped dicts
23- Use `Optional[T]` or `T | None` for nullable values
24- Leverage Pydantic's validation features (Field, validator decorators)
25- Run mypy before committing changes
26 
27## 3. Security-First Design
28 
29- **CRITICAL**: All mutating operations MUST require `confirm=True` parameter
30- Implement `dry_run=True` mode for preview-before-apply
31- Log all operations to `audit.log` with context (user, timestamp, parameters)
32- Use password masking utilities for sensitive data in logs
33- Validate and sanitize all user inputs
34- Follow least-privilege principle for API access
35- Never commit API keys, passwords, or secrets to version control
36 
37## 4. Comprehensive Testing
38 
39- Write tests FIRST for new features (TDD approach)
40- Target 80%+ code coverage for all new code
41- Use pytest fixtures for common setup
42- Mock external dependencies (UniFi API, Redis) in unit tests
43- Mark integration tests with `@pytest.mark.integration`
44- Test edge cases, error conditions, and validation failures
45- **NEVER** commit code that breaks existing tests
46 
47## 5. Documentation Standards
48 
49- Write clear, comprehensive docstrings for all public functions
50- Use Google-style docstring format
51- Include Args, Returns, Raises sections
52- Provide usage examples in docstrings for complex tools
53- Update API.md when adding new tools or changing signatures
54- Keep README.md current with project capabilities
55