11---
2- description:
3- globs:
4- alwaysApply: false
5- ---
6- ---
2+ description: Huntarr development rules and patterns
3+ globs: ["**/*.py", "**/*.js", "**/*.html", "**/*.css", "**/*.md"]
74alwaysApply: true
85---
9-
106# Huntarr Development Rules for Cursor AI
117
128## 🚨 CRITICAL MANDATORY RULES
@@ -89,12 +85,35 @@ conn = sqlite3.connect('/config/huntarr.db')
8985- Use debug borders to test CSS loading: `border: 2px solid lime !important;`
9086- Files: `/frontend/static/css/responsive-fix.css`, `/frontend/static/css/new-style.css`
9187
88+ ### Hard-Coded Path Issues
89+ - NEVER use hard-coded Docker paths that don't exist on bare metal
90+ - Use environment detection pattern with DatabaseManager
91+ - Test both Docker and local environments
92+
93+ ### JavaScript Variable Undefined Errors
94+ - Ensure all variables are declared before use in form generation
95+ - File: `/frontend/static/js/settings_forms.js`
96+
97+ ### Subpath Compatibility Issues
98+ - Works at root domain but fails in subdirectories
99+ - Use relative URLs everywhere: `./api/` not `/api/`
100+
101+ ### Info Icon Documentation Link Issues
102+ - Use proper GitHub documentation pattern with specific anchors
103+ - Pattern: `https://plexguide.github.io/Huntarr.io/apps/[app-name].html#[anchor]`
104+ - Always include `target="_blank" rel="noopener"` attributes
105+
106+ ### GitHub API Rate Limiting Issues
107+ - Use GitHub Actions + static manifest approach instead of direct API calls
108+ - Fetch from static manifest.json updated by GitHub Actions
109+
92110## 📁 KEY FILE LOCATIONS
93111
94112### Backend Core
95113- `/src/primary/utils/database.py` - DatabaseManager class (USE THIS)
96114- `/src/primary/routes/common.py` - API endpoints
97115- `/src/primary/auth.py` - Authentication logic
116+ - `/src/primary/cycle_tracker.py` - Timer functionality
98117
99118### Frontend Core
100119- `/frontend/static/js/new-main.js` - Main UI logic
@@ -149,6 +168,12 @@ conn = sqlite3.connect('/config/huntarr.db')
149168- ❌ Testing only in Docker
150169- ❌ Not using virtual environment for local development
151170- ❌ Creating temporary files instead of fixing source
171+ - ❌ Inconsistent behavior between missing/upgrade logic
172+ - ❌ Reactive violation fixing (scan proactively instead)
173+ - ❌ Documentation that promises non-existent features
174+ - ❌ Frontend links without verifying documentation anchors exist
175+ - ❌ Organic feature growth without reality checks
176+ - ❌ Theoretical FAQ content (base on real user problems)
152177
153178## 🚨 PROACTIVE VIOLATION SCANNING
154179
@@ -157,6 +182,17 @@ conn = sqlite3.connect('/config/huntarr.db')
1571822. Documentation violations: `grep -r "href.*plexguide.github.io" frontend/ --include="*.js" | grep -v "plexguide.github.io/Huntarr.io"`
1581833. Database violations: `grep -r "sqlite3.connect\|import sqlite3" src/ --include="*.py" | grep -v "database.py"`
1591844. Hard-coded path violations: `grep -r "/config" src/ --include="*.py" | grep -v "_detect_environment\|_get.*path\|DatabaseManager"`
185+ 5. JSON file operations: `grep -r "\.json\|json.load\|json.dump" src/ --include="*.py" | grep -v "requests.*json\|response.json\|Content-Type.*json"`
186+
187+ ### Violation Scanning Commands
188+ ```bash
189+ # Create violation_scan.sh for easy reuse
190+ echo "=== HUNTARR VIOLATION SCAN ==="
191+ echo "1. Absolute URL violations: $(grep -r "fetch('/api/" frontend/ --include="*.js" | wc -l)"
192+ echo "2. Documentation violations: $(grep -r "href.*plexguide.github.io" frontend/ --include="*.js" | grep -v "plexguide.github.io/Huntarr.io" | wc -l)"
193+ echo "3. Database violations: $(grep -r "sqlite3.connect\|import sqlite3" src/ --include="*.py" | grep -v "database.py" | wc -l)"
194+ echo "4. Hard-coded path violations: $(grep -r "/config" src/ --include="*.py" | grep -v "_detect_environment\|_get.*path\|DatabaseManager" | wc -l)"
195+ ```
160196
161197## 📊 SPECIFIC BUG PATTERNS TO AVOID
162198
@@ -172,6 +208,16 @@ conn = sqlite3.connect('/config/huntarr.db')
172208- Use DatabaseManager with proper Windows AppData support
173209- Never hard-code database paths
174210
211+ ### Frontend Log Regex Issues
212+ - Malformed regex with double backslashes
213+ - Fix: Use clean regex patterns without double backslashes
214+ - File: `/frontend/static/js/new-main.js` - `connectEventSource()` method
215+
216+ ### DEBUG Log Filtering Race Condition
217+ - DEBUG logs appear in wrong filters (Info, Warning, Error)
218+ - Fix: Apply filter to new entries as they arrive in EventSource
219+ - File: `/frontend/static/js/new-main.js` - `connectEventSource()` method
220+
175221## 🎯 DEBUGGING APPROACH
176222
177223### Systematic Issue Discovery
@@ -190,8 +236,48 @@ docker exec huntarr sqlite3 /config/huntarr.db ".tables"
190236# Local environment
191237ls -la ./data/huntarr.db
192238sqlite3 ./data/huntarr.db ".tables"
239+
240+ # Test DatabaseManager operations
241+ python3 -c "from src.primary.utils.database import DatabaseManager; db = DatabaseManager(); print('Database path:', db.db_path)"
193242```
194243
244+ ### Subpath Deployment Debugging
245+ - Check browser network tab for 404s on absolute URLs
246+ - Search for absolute patterns: `grep -r "fetch('/api" frontend/`
247+ - Check redirects: `grep -r "window.location.href.*= '/" frontend/`
248+ - Verify all URLs are relative: `./api/` not `/api/`
249+
250+ ### Frontend-Documentation Link Debugging
251+ - Extract frontend anchor references: `grep -r "href.*#" frontend/static/js/ | grep -o "#[^\"]*"`
252+ - Extract doc anchors: `grep -r 'id="[^"]*"' docs/ | grep -o 'id="[^"]*"'`
253+ - Compare lists to find mismatches
254+
255+ ### Log Issues Debugging
256+ 1. Check logs in database: `docker exec huntarr python3 -c "import sys; sys.path.insert(0, '/app/src'); from primary.utils.logs_database import get_logs_database; db = get_logs_database(); logs = db.get_logs(limit=10); [print(f'{log["timestamp"]} - {log["app_type"]} - {log["level"]} - {log["message"]}') for log in logs]"`
257+ 2. Test backend streaming: `curl -N -s "http://localhost:9705/logs?app=[app]"`
258+ 3. Check browser console for JavaScript errors
259+ 4. Verify regex patterns in `new-main.js`
260+
261+ ### Settings Issues Debugging
262+ 1. Check form generation functions
263+ 2. Verify `getFormSettings()` method
264+ 3. Test save/load cycle
265+ 4. Check API endpoints
266+ 5. Verify info icon links point to existing documentation anchors
267+
268+ ### CSS Issues Debugging
269+ 1. Check browser console for errors
270+ 2. Add debug borders: `border: 2px solid lime !important;`
271+ 3. Verify CSS loading order (external files vs inline)
272+ 4. Test specificity with `!important` declarations
273+ 5. Search for conflicting rules: `grep -r "className" frontend/static/css/`
274+
275+ ### Documentation Issues Debugging
276+ 1. Test all links manually or with link checker
277+ 2. Verify features mentioned actually exist in codebase
278+ 3. Check frontend alignment with documentation
279+ 4. Audit FAQ against real support requests
280+
195281## 📝 MEMORY CREATION GUIDELINES
196282
197283Create memories for:
@@ -225,7 +311,11 @@ This file automatically enforces the patterns from `.github/listen.md`. The user
225311- Following cross-platform compatibility requirements
226312- Getting approval before committing changes
227313- Using proper documentation links with verified anchors
314+ - Proactive violation scanning before commits
315+ - Systematic debugging approaches
316+ - Database-first development patterns
317+ - Cross-platform path handling
228318
229319---
230320
231- **REMEMBER: These rules are automatically applied. Follow them without being reminded.**
321+ **REMEMBER: These rules are automatically applied. Follow them without being reminded.**
0 commit comments