MovieMapper/AGENTS.md

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