Skip to content

Commit a3d29d6

Browse files
Admin9705Admin9705
committed
Refactor database access logic for improved stability and performance on Windows
1 parent b6012f4 commit a3d29d6

File tree

1 file changed

+231
-0
lines changed

1 file changed

+231
-0
lines changed

‎.cursor/rules/huntarr-development.mdc‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
---
7+
alwaysApply: true
8+
---
9+
10+
# Huntarr Development Rules for Cursor AI
11+
12+
## 🚨 CRITICAL MANDATORY RULES
13+
14+
### NEVER AUTO-COMMIT
15+
- NEVER automatically commit changes without explicit user approval
16+
- Always present fixes to user first and get explicit approval before committing
17+
- Let user decide when to commit
18+
19+
### MANDATORY TESTING WORKFLOW
20+
- ALWAYS rebuild and test changes using: `cd /Users/home/Huntarr/Huntarr.io && docker-compose down && COMPOSE_BAKE=true docker-compose up -d --build`
21+
- ALWAYS check logs for errors: `docker logs huntarr`
22+
- Test in both Docker and local environments
23+
24+
### CROSS-PLATFORM REQUIREMENTS
25+
- NEVER use hard-coded absolute paths (e.g., `/config/file.json`)
26+
- ALWAYS use `os.path.join()` for path construction
27+
- ALWAYS use relative URLs in frontend (e.g., `./api/` not `/api/`)
28+
- ALWAYS test: Docker, Windows, Mac, Linux, subpaths (`domain.com/huntarr/`)
29+
30+
## 🗄️ DATABASE-FIRST DEVELOPMENT
31+
32+
### ALWAYS Use DatabaseManager
33+
- Use `DatabaseManager` class from `src/primary/utils/database.py` for ALL data operations
34+
- NEVER use direct SQLite calls (`sqlite3.connect()`)
35+
- NEVER use JSON file operations for persistent data
36+
- DatabaseManager auto-detects environment (Docker vs local)
37+
38+
### Database Locations
39+
- Docker: `/config/huntarr.db` (persistent volume)
40+
- Local: `{project_root}/data/huntarr.db`
41+
- Auto-detection handles path selection
42+
43+
### Code Pattern
44+
```python
45+
# ✅ CORRECT
46+
from src.primary.utils.database import DatabaseManager
47+
db = DatabaseManager()
48+
db.set_setting('app', 'key', 'value')
49+
50+
# ❌ NEVER DO THIS
51+
import sqlite3
52+
conn = sqlite3.connect('/config/huntarr.db')
53+
```
54+
55+
## 🌐 FRONTEND DEVELOPMENT RULES
56+
57+
### URL Patterns
58+
- ALWAYS use relative URLs: `./api/endpoint` not `/api/endpoint`
59+
- ALWAYS use relative redirects: `window.location.href = './'` not `'/'`
60+
- This ensures subpath deployment works (`domain.com/huntarr/`)
61+
62+
### Documentation Links
63+
- ALWAYS use GitHub documentation domain: `https://plexguide.github.io/Huntarr.io/`
64+
- ALWAYS include proper anchors that exist in documentation
65+
- ALWAYS verify anchors exist before linking
66+
- Pattern: `https://plexguide.github.io/Huntarr.io/apps/[app-name].html#[anchor]`
67+
68+
### JavaScript Patterns
69+
- ALWAYS declare variables before use in form generation
70+
- NEVER use double backslashes in regex patterns
71+
- ALWAYS handle undefined variables gracefully
72+
73+
## 🐛 COMMON ISSUE PREVENTION
74+
75+
### Log Regex Issues
76+
- Use clean regex patterns without double backslashes
77+
- Test regex patterns thoroughly
78+
- File: `/frontend/static/js/new-main.js` - `connectEventSource()` method
79+
80+
### Settings Form Issues
81+
- Include all field name variations for different apps
82+
- Readarr: `hunt_missing_books`, `hunt_upgrade_books`
83+
- Radarr: `hunt_missing_movies`, `hunt_upgrade_movies`
84+
- Sonarr/Lidarr/Whisparr/Eros: `hunt_missing_items`, `hunt_upgrade_items`
85+
- File: `/frontend/static/js/settings_forms.js`
86+
87+
### CSS Loading Order
88+
- Add responsive CSS to external files, not inline in components
89+
- Use debug borders to test CSS loading: `border: 2px solid lime !important;`
90+
- Files: `/frontend/static/css/responsive-fix.css`, `/frontend/static/css/new-style.css`
91+
92+
## 📁 KEY FILE LOCATIONS
93+
94+
### Backend Core
95+
- `/src/primary/utils/database.py` - DatabaseManager class (USE THIS)
96+
- `/src/primary/routes/common.py` - API endpoints
97+
- `/src/primary/auth.py` - Authentication logic
98+
99+
### Frontend Core
100+
- `/frontend/static/js/new-main.js` - Main UI logic
101+
- `/frontend/static/js/settings_forms.js` - Settings forms
102+
- `/frontend/templates/components/` - UI components
103+
104+
### Database Files
105+
- Docker: `/config/huntarr.db`
106+
- Local: `./data/huntarr.db`
107+
108+
## 🔧 DEVELOPMENT WORKFLOW
109+
110+
### Before Making Changes
111+
1. Check current directory: `/Users/home/Huntarr/Huntarr.io`
112+
2. Activate venv for local development: `source venv/bin/activate`
113+
3. Review these rules
114+
115+
### Making Changes
116+
1. Edit source code (never modify inside container)
117+
2. For local testing: `python main.py` (uses ./data/huntarr.db)
118+
3. For Docker testing: `docker-compose down && COMPOSE_BAKE=true docker-compose up -d --build`
119+
4. Check logs: `docker logs huntarr`
120+
5. Test functionality in both environments
121+
122+
### Before Committing
123+
1. Test in Docker environment
124+
2. Test in local environment
125+
3. Test cross-platform compatibility
126+
4. Test subpath scenarios
127+
5. Check browser console for errors
128+
6. Verify database persistence across container restarts
129+
7. Get user approval before committing
130+
131+
## ⚠️ ANTI-PATTERNS TO AVOID
132+
133+
### Database Anti-Patterns
134+
- ❌ Direct SQLite calls: `sqlite3.connect()`
135+
- ❌ Hard-coded database paths: `/config/huntarr.db`
136+
- ❌ JSON file operations for persistent data
137+
- ❌ Not testing both Docker and local database operations
138+
139+
### Frontend Anti-Patterns
140+
- ❌ Absolute URLs: `/api/endpoint`, `window.location.href = '/'`
141+
- ❌ Wrong documentation domain links
142+
- ❌ Missing anchor verification
143+
- ❌ Double backslashes in regex
144+
- ❌ Inline responsive CSS in components
145+
146+
### Development Anti-Patterns
147+
- ❌ Modifying files inside containers
148+
- ❌ Auto-committing without approval
149+
- ❌ Testing only in Docker
150+
- ❌ Not using virtual environment for local development
151+
- ❌ Creating temporary files instead of fixing source
152+
153+
## 🚨 PROACTIVE VIOLATION SCANNING
154+
155+
### Before Every Commit, Check For:
156+
1. Absolute URL violations: `grep -r "fetch('/api/" frontend/ --include="*.js"`
157+
2. Documentation violations: `grep -r "href.*plexguide.github.io" frontend/ --include="*.js" | grep -v "plexguide.github.io/Huntarr.io"`
158+
3. Database violations: `grep -r "sqlite3.connect\|import sqlite3" src/ --include="*.py" | grep -v "database.py"`
159+
4. Hard-coded path violations: `grep -r "/config" src/ --include="*.py" | grep -v "_detect_environment\|_get.*path\|DatabaseManager"`
160+
161+
## 📊 SPECIFIC BUG PATTERNS TO AVOID
162+
163+
### GitHub Issue #626 Pattern (2FA Verification)
164+
- Check both `temp_2fa_secret` (setup) and `two_fa_secret` (enabled) in auth functions
165+
- File: `/src/primary/auth.py`
166+
167+
### GitHub Issue #624 Pattern (Settings Persistence)
168+
- Include all field name variations in form collection logic
169+
- File: `/frontend/static/js/settings_forms.js`
170+
171+
### GitHub Issue #629 Pattern (Windows Database Access)
172+
- Use DatabaseManager with proper Windows AppData support
173+
- Never hard-code database paths
174+
175+
## 🎯 DEBUGGING APPROACH
176+
177+
### Systematic Issue Discovery
178+
1. Don't guess - scan systematically first
179+
2. Use grep to find exact error patterns
180+
3. Check browser console for JavaScript errors
181+
4. Verify database operations in both environments
182+
5. Test cross-platform compatibility
183+
184+
### Database Debugging
185+
```bash
186+
# Docker environment
187+
docker exec huntarr ls -la /config/huntarr.db
188+
docker exec huntarr sqlite3 /config/huntarr.db ".tables"
189+
190+
# Local environment
191+
ls -la ./data/huntarr.db
192+
sqlite3 ./data/huntarr.db ".tables"
193+
```
194+
195+
## 📝 MEMORY CREATION GUIDELINES
196+
197+
Create memories for:
198+
- ✅ Bug fixes with root cause analysis
199+
- ✅ New features and their implementation patterns
200+
- ✅ Cross-platform compatibility fixes
201+
- ✅ Performance improvements
202+
- ✅ Database migration insights
203+
204+
## 🚀 DEPLOYMENT RULES
205+
206+
### Branch Management
207+
- Work on feature branches
208+
- Deploy to `dev` branch first
209+
- Merge `dev` to `main` after testing
210+
- Always pull latest changes before merging
211+
212+
### Testing Requirements
213+
- Test in Docker environment
214+
- Test in local development environment
215+
- Test cross-platform paths
216+
- Test subpath deployment scenarios
217+
- Verify database persistence
218+
219+
## 📋 FOLLOW .github/listen.md GUIDELINES
220+
221+
This file automatically enforces the patterns from `.github/listen.md`. The user should not need to remind you about:
222+
- Using DatabaseManager instead of direct SQLite
223+
- Using relative URLs instead of absolute URLs
224+
- Testing in both Docker and local environments
225+
- Following cross-platform compatibility requirements
226+
- Getting approval before committing changes
227+
- Using proper documentation links with verified anchors
228+
229+
---
230+
231+
**REMEMBER: These rules are automatically applied. Follow them without being reminded.**

0 commit comments

Comments
 (0)