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 with Jellyfin-compatible folder organization.

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)

Syntax Checking

• node --check renderer.js - Check renderer.js for syntax errors
• node --check main.js - Check main.js for syntax errors
• node --check utils/fileUtils.js - Check fileUtils.js for syntax errors

Linting

• No explicit linting tools configured in package.json
• Code style follows JavaScript/Node.js conventions
• Use JSDoc comments for documentation

Architecture Overview

Main Process (main.js)

• Handles all IPC communication with renderer
• File system operations (moving, renaming files)
• TheTVDB API integration with token authentication
• Audit logging to .audit files in directories
• Progress reporting via IPC events

Renderer Process (renderer.js)

• UI state management and DOM manipulation
• Event listeners for user interactions
• Tag management for files (extra, commentary)
• Progress spinner display during scanning
• Folder navigation and file display

File Utilities (utils/fileUtils.js)

• Non-recursive directory scanning (current folder only)
• FFmpeg integration for metadata extraction (duration, quality, fps)
• Progress callback support for UI updates
• Returns both folders and media files sorted (folders first)

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: { success: true/false, error?: string, ... }
• Use specific error messages with context information
• Implement proper error propagation throughout the application

IPC Communication Patterns

• Main process handlers use ipcMain.handle() for async operations
• Renderer invokes with ipcRenderer.invoke() returning promises
• Progress updates use mainWindow.webContents.send() for push events
• Renderer listens with ipcRenderer.on() for progress events
• Always return { success: boolean, ... } objects from IPC handlers

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 and styling (dark theme)
• 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 (TVDB_API_KEY)
• 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
• Use setImmediate yields when sending IPC messages in loops to allow event loop processing

Debugging

• Built-in debugging utilities for problematic files
• Console logging for development and debugging
• Error messages include context information
• Implement debug logging with timestamps via writeLog() function
• Use structured logging for better debugging experience
• Audit logs written to .audit files in each directory

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

Key Features Implementation

File Tagging System

• Files can be tagged as "extra" or "commentary"
• Tags stored as data attributes on DOM elements: data-tagged-extra, data-tagged-commentary
• Visual feedback with color changes and glow effects when tagged
• Play button enables only when file is tagged
• Individual play button moves single file
• Floating action button (FAB) moves all tagged files at once

Folder Navigation

• Non-recursive scanning shows only current directory contents
• Folders displayed with 📁 icon at top of list
• Clicking folder navigates into it and rescans
• openDirectory(path) function handles navigation

Progress Indication

• Spinner with file count shown during directory scanning
• Progress container hidden when not scanning
• IPC event scan-progress sends updates from main to renderer
• setImmediate yields ensure UI updates during processing

File Movement

• Files tagged "extra" move to "extras" folder (Jellyfin compatible)
• Files tagged "commentary" move to "commentary" folder
• Target folders created automatically if they don't exist
• Audit log entry written for each move operation
• Files removed from UI after successful move

Recent Changes (Session 2026-02-22)

Bug Fixes

1. Fixed duplicate moveTaggedFile function - Two definitions were overwriting each other
2. Fixed missing click handler for FAB - Added moveAllTaggedFiles() on floating circle click
3. Fixed "extra" vs "extras" folder naming - Now correctly uses "extras" for Jellyfin
4. Fixed progressBar reference error - Removed reference after switching to spinner
5. Removed non-existent test-api-btn reference - Was causing errors on load

New Features

1. Folder navigation - Click folders to navigate into them
2. Non-recursive scanning - Only shows current directory contents
3. Progress spinner - Shows file being processed with count
4. Batch file moving - FAB moves all tagged files at once
5. Visual feedback - FAB turns yellow while processing

UI Improvements

1. Dark theme - Modern dark color scheme (#1a1a2e, #16213e, #0f3460)
2. Clean layout - Search/shows on left sidebar, files on right
3. Accent color - Pink/red accent (#e94560)
4. Better typography - System font stack
5. Smooth animations - Hover effects and transitions

Jellyfin Compatible Folder Names

Extras Folders (place inside movie/show folder)

• behind the scenes - Behind-the-scenes content
• deleted scenes - Deleted scenes
• interviews - Cast/crew interviews
• scenes - Individual scenes
• samples - Sample clips
• shorts - Short films
• featurettes - Featurettes
• clips - Clips
• other - Generic catch-all for unknown extras
• extras - Generic catch-all for unknown extras (CURRENTLY IMPLEMENTED)
• trailers - Trailers and previews
• theme-music - Theme music audio files
• backdrops - Backdrop videos

Special Single-File Names (in same folder as media)

• trailer - Single trailer file
• sample - Single sample file
• theme - Theme song audio file

File Suffix Options (append to filename)

• -trailer, .trailer, _trailer, trailer
• -sample, .sample, _sample, sample
• -scene, -clip, -interview
• -behindthescenes, -deleted, -deletedscene
• -featurette, -short, -other, -extra

Known Issues & Future Work

Known Issues

• Progress spinner updates may be delayed due to IPC buffering
• No "go back" / parent directory navigation yet
• Tag state is lost on directory change (not persisted)

Suggested Improvements

1. Add parent directory navigation ("..") or breadcrumb
2. Persist tag state to avoid accidental loss
3. Add more Jellyfin folder type options (trailers, featurettes, etc.)
4. Add file renaming with episode matching from TVDB
5. Add batch rename functionality
6. Consider adding undo for file moves
7. Add confirmation dialog before moving files

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
• Always run syntax checks after modifying JS files: node --check <file>