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