Medios-Macina/USAGE_ADD_FILE_BATCH.md

# Add-File Batch Directory Mode

## Overview
The `add-file` cmdlet now supports scanning directories for batch file operations. When you provide a directory path with the `-path` argument and specify a `-store` location, add-file will:

1. **Scan** the directory for all supported media files
2. **Hash** each file (SHA256)
3. **Display** a result table with filename, hash, size, and extension
4. **Wait** for your selection using `@N` syntax
5. **Add** only the selected files to your store

## Usage

### Basic Syntax
```bash
add-file -path <directory> -store <store-name>
```

### Step-by-Step Example

#### Step 1: Scan directory and show table
```bash
add-file -path "C:\Users\Admin\Downloads\test_add_file" -store mystore
```

Output:
```
✓ Found 3 files in directory. Use @N syntax to select (e.g., @1 or @1-3)

Files in Directory
─────────────────────────────────────────────────────────
 #  │ name          │ hash         │ size    │ ext
────────────────────────────────────────────────────────────
 1  │ image1.jpg    │ a3f9b2c1...  │ 2.3 MB  │ .jpg
 2  │ video1.mp4    │ d4e8f7a3...  │ 45.2 MB │ .mp4
 3  │ audio1.mp3    │ b1c9d2e3...  │ 3.8 MB  │ .mp3
```

The command **stops here** and waits for your selection - no files are processed yet.

#### Step 2: Select files using @N syntax
After the table is displayed, use one of these selection syntaxes:

```bash
# Add file 1 only
@1

# Add files 1 through 3
@1-3

# Add files 1, 2, and 3
@1,@2,@3

# Add files 2 and 3
@2-3
```

The selected file(s) are then piped back to `add-file` for processing and added to your store.

## Workflow Diagram

```
User Command:
┌─────────────────────────────────────────────────────┐
│ add-file -path "D:\media" -store mystore            │
└─────────────────────────────────────────────────────┘
                        ↓
            ┌───────────────────────┐
            │ STEP 1: Scan & Display│
            │ - Scan directory      │
            │ - Compute hashes      │
            │ - Show result table   │
            │ - WAIT for @N input   │
            └───────────────────────┘
                        ↓
User Response:
┌─────────────────────────────────────────────────────┐
│ @1,@3                    (select files 1 and 3)     │
└─────────────────────────────────────────────────────┘
                        ↓
            ┌───────────────────────┐
            │ STEP 2: Process Files │
            │ - Get selected items  │
            │ - Copy to store       │
            │ - Show results        │
            └───────────────────────┘
                        ↓
        Files added successfully!
```

## Supported File Types
The directory scanner supports all media files defined in `SUPPORTED_MEDIA_EXTENSIONS`:
- **Images**: .jpg, .jpeg, .png, .gif, .webp, .bmp, .tiff
- **Videos**: .mp4, .mkv, .webm, .mov, .avi, .flv, .mpg, .mpeg, .ts, .m4v, .wmv
- **Audio**: .mp3, .flac, .wav, .m4a, .aac, .ogg, .opus, .wma, .mka
- **Documents**: .pdf, .epub, .txt, .mobi, .azw3, .cbz, .cbr, .doc, .docx

## Key Behavior Notes

1. **No immediate processing**: Directory scan shows table and returns without copying/adding any files
2. **User control**: Nothing happens until the user makes an `@N` selection
3. **Batch selection**: Multiple files can be selected with comma or range syntax
4. **Hash display**: Each file's SHA256 is displayed (first 12 chars in table)
5. **Error handling**: Unsupported file types are automatically filtered out

## Implementation Details

### New Methods Added
- **`_scan_directory_for_files(directory: Path)`**: Static method that scans a directory and returns a list of dicts with:
  - `path`: Path object to the file
  - `name`: Filename
  - `hash`: SHA256 hash
  - `size`: File size in bytes
  - `ext`: File extension

### Modified Methods
- **`run()`**: 
  - Detects when `-path` is a directory AND `-store` is provided
  - Calls `_scan_directory_for_files()` to build the file list
  - Displays result table
  - **Returns early (return 0) without processing** - this is key!
  - User selection via `@N` pipes selected items back to add-file for processing

- **`_resolve_source()`**: 
  - Added priority for directory scan results (path + hash keys)
  - Handles items coming from @N selection seamlessly

## Error Handling
- If directory doesn't exist or isn't readable, returns error
- If a file fails to hash, it's skipped with debug output logged
- Unsupported file types are automatically filtered out during scan