# 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>`