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

Linting

• No explicit linting tools configured in package.json
• Code style follows JavaScript/Node.js conventions

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

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)

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)

Types

• This is a JavaScript project without TypeScript
• Use JSDoc comments to document function parameters and return values
• Use descriptive parameter names

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

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

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

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

Debugging

• Built-in debugging utilities for problematic files
• Console logging for development and debugging
• Error messages include context information