# 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