107 lines
4.5 KiB
Markdown
107 lines
4.5 KiB
Markdown
# MovieMapper Agent Guidelines
|
|
|
|
## Project Overview
|
|
MovieMapper is an Electron-based desktop application for organizing and managing movie and TV show collections. It provides features for browsing media files, searching TV shows using TheTVDB API, and managing file metadata.
|
|
|
|
## Build/Lint/Test Commands
|
|
|
|
### Build Commands
|
|
- `npm install` - Install project dependencies
|
|
- `npm start` - Run the application using Electron
|
|
- `electron .` - Alternative way to run the application
|
|
|
|
### Test Commands
|
|
- `npm test` - Currently outputs "Error: no test specified" (default test script)
|
|
- `node test-api.js` - Run API connectivity test for TheTVDB
|
|
- `node main.js` - Run main process directly for debugging (may require environment setup)
|
|
|
|
### Linting
|
|
- No explicit linting tools configured in package.json
|
|
- Code style follows JavaScript/Node.js conventions
|
|
- Use JSDoc comments for documentation
|
|
|
|
## Code Style Guidelines
|
|
|
|
### Imports
|
|
- Use standard Node.js `require()` syntax for modules
|
|
- Import modules at the top of files
|
|
- Group imports by standard library, external modules, then local modules
|
|
- Use descriptive names for modules (e.g., `const fs = require('fs')`)
|
|
|
|
### Formatting
|
|
- Use 2-space indentation
|
|
- Use single quotes for strings
|
|
- Place opening braces on the same line as the statement
|
|
- Add spaces around operators and after commas
|
|
- No semicolons required (follows JavaScript convention)
|
|
- Use consistent spacing around code blocks
|
|
|
|
### Naming Conventions
|
|
- Use camelCase for variables and functions
|
|
- Use PascalCase for constructors
|
|
- Use UPPER_CASE for constants
|
|
- Use descriptive variable names
|
|
- Function names should be verbs (e.g., `scanDirectory`, `extractFileMetadata`)
|
|
- File names should be lowercase with hyphens (e.g., `file-utils.js`)
|
|
|
|
### Types
|
|
- This is a JavaScript project without TypeScript
|
|
- Use JSDoc comments to document function parameters and return values
|
|
- Use descriptive parameter names
|
|
- Include type information in comments for complex objects
|
|
|
|
### Error Handling
|
|
- Use try/catch blocks for async operations
|
|
- Handle file system errors gracefully
|
|
- Log warnings for problematic files but don't crash the application
|
|
- Return consistent error structures from async functions
|
|
- Use specific error messages with context information
|
|
- Implement proper error propagation throughout the application
|
|
|
|
### File Structure
|
|
- `main.js` - Electron main process handling IPC and application lifecycle
|
|
- `renderer.js` - Electron renderer process managing UI interactions
|
|
- `index.html` - Main HTML structure
|
|
- `utils/fileUtils.js` - File scanning and metadata extraction utilities
|
|
- `.env` - Environment configuration file for API keys
|
|
- `app-debug.log` - Application debug log file (created at startup)
|
|
|
|
### API Integration
|
|
- TheTVDB v4 API integration using bearer token authentication
|
|
- Proper error handling for API calls
|
|
- Fallback mechanisms when metadata extraction fails
|
|
- Environment variables for API keys
|
|
- Implement authentication token caching for performance
|
|
|
|
### Code Patterns
|
|
- Use async/await for handling asynchronous operations
|
|
- Handle permission errors gracefully when scanning directories
|
|
- Provide user feedback through console warnings for problematic files
|
|
- Use descriptive variable names that reflect their purpose
|
|
- Implement comprehensive logging for debugging
|
|
- Use consistent IPC patterns for communication between main and renderer processes
|
|
|
|
### Debugging
|
|
- Built-in debugging utilities for problematic files
|
|
- Console logging for development and debugging
|
|
- Error messages include context information
|
|
- Implement debug logging with timestamps
|
|
- Use structured logging for better debugging experience
|
|
|
|
### Environment Configuration
|
|
- API keys stored in `.env` file
|
|
- Environment variables should be validated on application startup
|
|
- Provide clear error messages when environment variables are missing
|
|
- Use `dotenv` package for loading environment variables
|
|
|
|
## Special Notes
|
|
- The application uses Electron for cross-platform desktop functionality
|
|
- File scanning uses recursive directory traversal with proper error handling
|
|
- Media file processing uses ffmpeg for metadata extraction
|
|
- IPC handlers are implemented using Electron's ipcMain for communication between processes
|
|
- The application supports moving files to "extra" and "commentary" folders
|
|
- API connectivity testing is implemented for TheTVDB v4 integration
|
|
|
|
## Execution Constraints
|
|
- All commands that might block indefinitely must be run with a timeout
|
|
- Example: `timeout 30 npm start` to run the application with 30-second timeout |