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

add-file -path <directory> -store <store-name>

Step-by-Step Example

Step 1: Scan directory and show table

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:

# 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