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

Test Commands

• node test-api.js - Test TheTVDB API connectivity
• node test-command-line.js - Test command-line argument parsing
• node test-audit.js - Run unit tests for audit logging (uses node:test)
• node test-functional.js - Run functional tests for UI elements
• node test-core.js - Verify core functionality implementation
• node test-implementation.js - Test implemented features
• node test-audit-functionality.js - Test audit file operations

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

Running Single Tests

Use node <test-file>.js to run individual test files. Tests use Node.js built-in node:test framework.

Linting

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

Architecture Overview

Main Process (main.js)

• Electron main process handling application lifecycle
• IPC handlers for renderer communication (ipcMain.handle())
• File system operations (moving, renaming, scanning)
• TheTVDB API integration with token authentication
• Audit logging to .audit files in directories
• Progress reporting via mainWindow.webContents.send()

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
• Import modules at the top of files
• Group imports: standard library → external modules → local modules
• Use descriptive names: const fs = require('fs')

Formatting

• 2-space indentation
• Single quotes for strings
• Opening braces on same line as statement
• Spaces around operators and after commas
• No semicolons required
• Consistent spacing around code blocks

Naming Conventions

• camelCase for variables and functions
• PascalCase for constructors
• UPPER_CASE for constants
• Function names should be verbs (e.g., scanDirectory, extractFileMetadata)
• File names lowercase with hyphens (e.g., file-utils.js)

Types

• JavaScript project without TypeScript
• Use JSDoc comments for function parameters and return values
• 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 without crashing
• 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 uses 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 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 main/renderer communication
• Use setImmediate yields when sending IPC messages in loops

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 (root level only)
• Environment variables validated on application startup
• Clear error messages when environment variables missing
• Use dotenv package for loading environment variables

Key Features Implementation

File Tagging System

• Files tagged as "extra" or "commentary"
• Tags stored as data attributes: data-tagged-extra, data-tagged-commentary
• Visual feedback with color changes and glow effects
• 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

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 run with timeout
• Example: timeout 30 npm start to run with 30-second timeout
• Always run syntax checks after modifying JS files: node --check <file>

Jellyfin Compatible Folder Names

Extras Folders (place inside movie/show folder)

• behind the scenes, deleted scenes, interviews, scenes, samples, shorts, featurettes, clips, other, extras, trailers, theme-music, backdrops

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

• trailer, sample, theme

File Suffix Options (append to filename)

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