CLI Enhancements: Multiple Files, Stdin, Magic Discovery

[unclesp1d3r]

CLI Enhancements: Multiple Files, Stdin, Magic Discovery

Overview

Enhance the CLI to support multiple file arguments, stdin input, improved magic file discovery with text-first priority, and --use-builtin / --strict flags. This completes the end-to-end user experience for Phase 1 MVP.

Validation Findings (Implementation Validation)

Bugs in Existing Code to Fix:

1. BUG: Magic file search order wrong (file:src/main.rs lines 64-76)

   • Current: Binary .mgc files searched FIRST
   • Required: Text files/directories FIRST (OpenBSD approach)
   • Impact: Users will encounter unsupported binary .mgc before finding text files
   • Fix: Reorder search candidates to prioritize Magdir directories and text files

2. BUG: create_basic_magic_content() should not exist (file:src/main.rs lines 428-484)

   • Current: 483 lines of basic magic file generation code
   • Required: Remove entirely (--create-magic flag was eliminated from scope)
   • Impact: Dead code, maintenance burden
   • Fix: Delete function and all references

3. BUG: Missing --use-builtin and --strict flags (file:src/main.rs lines 23-39)

   • Current: Flags not defined in Args struct
   • Required: Add both flags per Core Flow 3 and Technical Plan
   • Impact: Users cannot use built-in rules or control exit code behavior
   • Fix: Add flags to Args struct and implement logic

Scope

In Scope:

• Multiple file argument support (sequential processing)
• Stdin input support (using clap-stdin crate with - as file argument)
• Text-first magic file search paths (Magdir directories before .mgc files)
• --use-builtin flag (use built-in rules)
• --strict flag (exit non-zero on any failure, default: exit 0)
• Exit code handling (default: 0 even if some fail, strict: non-zero on any fail)
• JSON Lines output for multiple files
• Error handling per file (continue on failure)

Out of Scope:

• Progress indicators (deferred to Phase 2)
• Batch optimization (deferred to Phase 2)
• Advanced CLI features (deferred to Phase 2)

Technical Approach

1. Multiple File Support

Update file:src/main.rs to use clap-stdin:

use clap_stdin::FileOrStdin;

#[derive(Parser)]
struct Args {
    /// File to analyze (use '-' for stdin)
    #[arg(value_name = "FILE")]
    pub files: Vec<FileOrStdin>,

    // ... existing flags ...

    /// Exit with non-zero code if any file fails
    #[arg(long)]
    pub strict: bool,
}

Processing Logic:

let mut exit_code = 0;
for file in &args.files {
    match db.evaluate_file(file) {
        Ok(result) => output_result(file, &result, &args)?,
        Err(e) => {
            eprintln!("{}: Error: {}", file.display(), e);
            exit_code = 3;
            if args.strict {
                std::process::exit(exit_code);
            }
        }
    }
}
std::process::exit(exit_code);

2. Stdin Support

Using clap-stdin's FileOrStdin:

for file_or_stdin in &args.files {
    match file_or_stdin {
        FileOrStdin::Stdin => {
    let mut buffer = Vec::new();
    let max_size = config.max_string_length;

    io::stdin()
        .take(max_size as u64)
        .read_to_end(&mut buffer)?;

    if buffer.len() >= max_size {
        eprintln!("Warning: Stdin truncated at {} bytes", max_size);
    }

    let result = db.evaluate_buffer(&buffer)?;
    output_result("stdin", &result, &args)?;
    return Ok(());
}

3. Text-First Magic Discovery

Update Args::default_magic_file_path():

let candidates = [
    // Text files/directories FIRST (OpenBSD approach)
    "/usr/share/file/magic/Magdir",
    "/usr/share/misc/magic",
    "/usr/local/share/misc/magic",

    // Binary .mgc files LAST (show helpful error)
    "/usr/share/file/magic.mgc",
    "/usr/local/share/misc/magic.mgc",
];

4. Built-in Rules Flag

#[arg(long)]
pub use_builtin: bool,

#[arg(long)]
pub strict: bool,

// In main():
let db = if args.use_builtin {
    MagicDatabase::with_builtin_rules()
} else if let Some(ref magic_file) = args.magic_file {
    MagicDatabase::load_from_file(magic_file)?
} else {
    discover_and_load_magic_database()?
};

5. Exit Code Handling

let mut exit_code = 0;
for file in &args.files {
    match db.evaluate_file(file) {
        Ok(result) => output_result(file, &result, &args)?,
        Err(e) => {
            eprintln!("{}: Error: {}", file.display(), e);
            if args.strict {
                std::process::exit(3);
            }
            exit_code = 3;
        }
    }
}
if args.strict && exit_code != 0 {
    std::process::exit(exit_code);
}
std::process::exit(0); // Default: exit 0 even if some failed

6. Removed: Create Magic Flag

#[arg(long)]
pub create_magic: bool,

// In discover_and_load_magic_database():
if args.create_magic {
    let magic_path = default_magic_file_path();
    if let Err(e) = create_basic_magic_file(&magic_path) {
        eprintln!("Failed to create magic file: {}", e);
        eprintln!("Suggestion: Use --use-builtin instead");
        std::process::exit(4);
    }
    return MagicDatabase::load_from_file(&magic_path);
}

6. JSON Lines Output

fn output_json(filename: &str, result: &EvaluationResult) -> Result<()> {
    let json = serde_json::json!({
        "filename": filename,
        "matches": [...],
        "metadata": {...}
    });
    println!("{}", serde_json::to_string(&json)?);
    Ok(())
}

Acceptance Criteria

• CLI accepts multiple file arguments
• Each file processed sequentially with immediate output
• Stdin input works with - or --stdin
• Stdin respects max_string_length limit
• Text magic files searched before binary .mgc
• --use-builtin flag loads built-in rules
• --strict flag exits non-zero on any failure
• Default behavior: exit 0 even if some files fail (GNU file compatible)
• Per-file timeout: each file gets full timeout duration
• Timeout doesn't stop processing of remaining files
• Stdin uses clap-stdin FileOrStdin pattern
• Stdin respects max_string_length as buffer size limit
• --strict with --use-builtin: "data" result is not an error
• Rustdoc added for all new CLI flags
• JSON Lines format for multiple files
• Text format: one line per file
• Error messages show filename context
• Unit tests for all new flags
• Integration tests for multiple files
• Integration test for stdin

Dependencies

• Hard Dependency: ticket:75a688c2-0ac4-489a-a35d-6e824c94c153/c554e409-ae60-407f-9596-64c5b03a9b92 (Parser Integration) - Required for magic file loading
• Soft Dependency: ticket:75a688c2-0ac4-489a-a35d-6e824c94c153/5fa9fb36-a0bf-4d1b-924a-41a0a39f126e (Built-in Rules) - Can implement with stub initially, complete when built-in rules are ready

Related Specs

• spec:75a688c2-0ac4-489a-a35d-6e824c94c153/36539700-862d-4fdf-9c79-3c36390f6aa8 (Core Flows - Flows 1, 2, 3, 10)
• spec:75a688c2-0ac4-489a-a35d-6e824c94c153/269e848a-258d-4cd4-99b1-386bd400a109 (Technical Plan - CLI Enhancements)

Files to Modify

• file:src/main.rs - Add multiple file support, stdin, flags, discovery logic
• file:tests/cli_integration_tests.rs - Add integration tests

[traycerai]

Plan

Observations

The current CLI implementation in file:src/main.rs accepts only a single file argument and lacks stdin support. The magic file discovery logic exists but has two critical bugs: (1) binary .mgc files are searched FIRST instead of text files/directories, and (2) the create_basic_magic_content() function is dead code that should be removed. The Args struct is missing the --use-builtin and --strict flags required for Phase 1 MVP. The output infrastructure (file:src/output/mod.rs, file:src/output/json.rs, file:src/output/text.rs) is well-designed and ready to handle multiple file results.

Approach

The implementation will follow the GNU file command conventions: accept multiple file arguments via clap-stdin's FileOrStdin type, support stdin input using - as a file argument, reorder magic file discovery to prioritize text files/directories (OpenBSD approach), and add --use-builtin and --strict flags. The changes will be focused on the CLI layer in file:src/main.rs, leveraging the existing evaluation and output infrastructure. Each file will be processed sequentially with immediate output to maintain streaming behavior and handle large file lists efficiently. Exit code handling will default to 0 even if some files fail (GNU file compatible), with --strict mode exiting non-zero on any failure.

Implementation Steps

1. Fix Magic File Search Order (BUG FIX)

Update the default_magic_file_path() function in file:src/main.rs (lines 61-116):

• Reorder candidates to prioritize text files/directories FIRST (OpenBSD approach)
• Place binary .mgc files LAST
• Check environment variables (MAGIC, MAGIC_FILE) before hardcoded paths
• Maintain CI/CD environment detection logic

New order:

1. Environment variables (MAGIC, MAGIC_FILE)
2. Text magic directories (/usr/share/file/magic/Magdir, /usr/share/misc/magic)
3. Text magic files (/etc/magic, /usr/local/share/misc/magic)
4. Binary .mgc files (/usr/share/file/magic.mgc, etc.)
5. Development/CI fallback (third_party/magic.mgc)

2. Remove Dead Code (BUG FIX)

Delete the create_basic_magic_content() function (lines 428-484) and all references to it:

• Remove function definition
• Remove call in download_magic_files() (line 420)
• Update download_magic_files() to return error if magic file not found (no fallback creation)
• Remove --create-magic flag from Args struct (if present)

3. Update CLI Argument Structure

Modify the Args struct in file:src/main.rs (lines 23-39):

• Change file: PathBuf to files: Vec<FileOrStdin> to accept multiple file arguments
• Make the files argument optional with #[arg(value_name = "FILE")]
• Add --use-builtin flag: #[arg(long)] to use built-in rules
• Add --strict flag: #[arg(long)] to exit non-zero on any failure
• Add Rustdoc comments for all new flags
• Keep existing --json, --text, and --magic-file options unchanged

4. Add clap-stdin Dependency

Update Cargo.toml:

• Add clap-stdin = "0.1" to dependencies
• This provides FileOrStdin type for handling - as stdin argument

5. Implement Stdin Support

Add a new function read_from_stdin() in file:src/main.rs:

• Read all data from std::io::stdin() into a buffer
• Respect max_string_length limit (e.g., 1GB) to prevent memory exhaustion
• Return buffer and display name "<stdin>" for output formatting
• Handle errors gracefully (empty stdin, read errors)

6. Implement Multi-File Processing

Refactor the run_analysis() function in file:src/main.rs (lines 215-294):

• Handle empty files vector: read from stdin if no files provided
• Create a new function process_single_file(file_or_stdin: &FileOrStdin, db: &MagicDatabase, args: &Args) that evaluates one file and returns a result
• Iterate through all input sources (files or stdin)
• For each source, call process_single_file() and immediately output the result
• Continue processing remaining files even if one fails (collect errors but don't abort)
• Track exit code: 0 by default, 3 if any file fails, exit immediately if --strict is set

7. Update Output Formatting

Modify output logic in run_analysis():

• For text format: use "{}: {}" pattern for each file (e.g., "file.bin: ELF 64-bit")
• For JSON format: output JSON Lines format (one JSON object per line) for multiple files
• Handle stdin display: show "<stdin>" or "-" as the filename
• Ensure each file's output appears on its own line in text mode

8. Implement Built-in Rules Flag

Add logic to run_analysis():

• If --use-builtin is set, use MagicDatabase::with_builtin_rules()
• If --magic-file is provided, use that file
• Otherwise, discover and load magic database using updated search order
• Prioritize: --use-builtin > --magic-file > discovery

9. Implement Strict Mode Exit Code Handling

Update exit code logic in main() and run_analysis():

• Default behavior: exit 0 even if some files fail (GNU file compatible)
• With --strict: exit non-zero (3) if any file fails
• Per-file errors: print to stderr with filename context
• Continue processing remaining files unless --strict is set

10. Update Validation Logic

Modify validation functions in file:src/main.rs:

• Update validate_arguments() to allow empty files vector (stdin mode)
• Keep validate_input_file() for individual file validation
• Add validation to ensure at least one input source (files or stdin)

11. Update Tests

Modify tests in file:src/main.rs and file:tests/cli_integration_tests.rs:

• Update existing tests to use files: vec![FileOrStdin::File(PathBuf::from("test.bin"))]
• Add tests for multiple file arguments: rmagic file1 file2 file3
• Add tests for stdin input: echo "data" | rmagic or rmagic -
• Add tests for mixed scenarios: rmagic file1 - file2
• Add tests for --use-builtin flag
• Add tests for --strict flag with success and failure cases
• Add tests for magic file discovery with environment variables
• Add tests for exit codes: 0 (success), 3 (file error), 5 (timeout)

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as main()
    participant Args as Args::parse()
    participant Discovery as Magic Discovery
    participant DB as MagicDatabase
    participant Processor as process_single_file()
    participant Output as Output Formatter

    User->>CLI: rmagic file1 file2 -
    CLI->>Args: Parse arguments
    Args-->>CLI: files=[file1, file2, stdin]
    
    alt --use-builtin flag set
        CLI->>DB: MagicDatabase::with_builtin_rules()
    else --magic-file provided
        CLI->>DB: MagicDatabase::load_from_file(magic_file)
    else discover magic file
        CLI->>Discovery: get_magic_file_path()
        Discovery->>Discovery: Check MAGIC env var
        Discovery->>Discovery: Check MAGIC_FILE env var
        Discovery->>Discovery: Check text directories/files
        Discovery->>Discovery: Check binary .mgc files
        Discovery->>Discovery: Check CI/dev fallback
        Discovery-->>CLI: magic_file_path
        CLI->>DB: MagicDatabase::load_from_file(magic_file_path)
    end
    
    DB-->>CLI: MagicDatabase instance
    
    loop For each file in files
        alt file is stdin
            CLI->>CLI: read_from_stdin()
            CLI->>Processor: process_single_file(stdin_buffer)
        else regular file
            CLI->>Processor: process_single_file(file)
        end
        
        Processor->>DB: evaluate_file()
        DB-->>Processor: EvaluationResult or Error
        
        alt Success
            Processor-->>CLI: Result
            CLI->>Output: format_output(result)
            Output-->>User: filename: description
        else Error
            Processor-->>CLI: Error
            CLI->>CLI: eprintln!("{}: Error: {}", filename, error)
            alt --strict mode
                CLI-->>User: Exit code 3
            else default mode
                CLI->>CLI: Continue to next file
            end
        end
    end
    
    alt --strict and any error
        CLI-->>User: Exit code 3
    else all succeeded or default mode
        CLI-->>User: Exit code 0
    end

Loading

Additional Considerations

Environment Variables: Support MAGIC and MAGIC_FILE environment variables in the magic file discovery logic, checking them before the hardcoded paths. This aligns with GNU file command behavior.

Stdin Buffer Management: When reading from stdin, use a reasonable buffer size limit (e.g., 1GB matching FileBuffer::MAX_FILE_SIZE) to prevent memory exhaustion attacks. Warn if stdin is truncated.

Output Consistency: Ensure that when processing multiple files, the output format remains consistent with GNU file command behavior, where each line shows filename: description in text mode and JSON Lines format in JSON mode.

Performance: Process files sequentially rather than in parallel to maintain output order and avoid resource contention, which aligns with GNU file command behavior.

Backward Compatibility: The changes maintain backward compatibility - existing single-file invocations like rmagic file.bin will continue to work without modification.

Exit Code Semantics:

• 0: All files processed successfully
• 3: One or more files failed (with --strict, exit immediately on first failure)
• 5: Timeout occurred
• Other codes: Parse errors (4), IO errors (3), etc.

JSON Lines Format: For multiple files with --json, output one JSON object per line (JSON Lines format), not a single array. This allows streaming processing and is compatible with tools like jq.

Stdin Behavior: When no files are provided, read from stdin. When - is provided as a file argument, read from stdin for that entry. Both behaviors should work identically.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current CLI implementation in `file:src/main.rs` accepts only a single file argument and lacks stdin support. The magic file discovery logic exists but has two critical bugs: (1) binary .mgc files are searched FIRST instead of text files/directories, and (2) the `create_basic_magic_content()` function is dead code that should be removed. The `Args` struct is missing the `--use-builtin` and `--strict` flags required for Phase 1 MVP. The output infrastructure (`file:src/output/mod.rs`, `file:src/output/json.rs`, `file:src/output/text.rs`) is well-designed and ready to handle multiple file results.

## Approach

The implementation will follow the GNU `file` command conventions: accept multiple file arguments via clap-stdin's `FileOrStdin` type, support stdin input using `-` as a file argument, reorder magic file discovery to prioritize text files/directories (OpenBSD approach), and add `--use-builtin` and `--strict` flags. The changes will be focused on the CLI layer in `file:src/main.rs`, leveraging the existing evaluation and output infrastructure. Each file will be processed sequentially with immediate output to maintain streaming behavior and handle large file lists efficiently. Exit code handling will default to 0 even if some files fail (GNU file compatible), with `--strict` mode exiting non-zero on any failure.

## Implementation Steps

### 1. Fix Magic File Search Order (BUG FIX)

Update the `default_magic_file_path()` function in `file:src/main.rs` (lines 61-116):

- Reorder candidates to prioritize text files/directories FIRST (OpenBSD approach)
- Place binary .mgc files LAST
- Check environment variables (`MAGIC`, `MAGIC_FILE`) before hardcoded paths
- Maintain CI/CD environment detection logic

New order:
1. Environment variables (`MAGIC`, `MAGIC_FILE`)
2. Text magic directories (`/usr/share/file/magic/Magdir`, `/usr/share/misc/magic`)
3. Text magic files (`/etc/magic`, `/usr/local/share/misc/magic`)
4. Binary .mgc files (`/usr/share/file/magic.mgc`, etc.)
5. Development/CI fallback (`third_party/magic.mgc`)

### 2. Remove Dead Code (BUG FIX)

Delete the `create_basic_magic_content()` function (lines 428-484) and all references to it:

- Remove function definition
- Remove call in `download_magic_files()` (line 420)
- Update `download_magic_files()` to return error if magic file not found (no fallback creation)
- Remove `--create-magic` flag from `Args` struct (if present)

### 3. Update CLI Argument Structure

Modify the `Args` struct in `file:src/main.rs` (lines 23-39):

- Change `file: PathBuf` to `files: Vec<FileOrStdin>` to accept multiple file arguments
- Make the `files` argument optional with `#[arg(value_name = "FILE")]`
- Add `--use-builtin` flag: `#[arg(long)]` to use built-in rules
- Add `--strict` flag: `#[arg(long)]` to exit non-zero on any failure
- Add Rustdoc comments for all new flags
- Keep existing `--json`, `--text`, and `--magic-file` options unchanged

### 4. Add clap-stdin Dependency

Update `Cargo.toml`:

- Add `clap-stdin = "0.1"` to dependencies
- This provides `FileOrStdin` type for handling `-` as stdin argument

### 5. Implement Stdin Support

Add a new function `read_from_stdin()` in `file:src/main.rs`:

- Read all data from `std::io::stdin()` into a buffer
- Respect `max_string_length` limit (e.g., 1GB) to prevent memory exhaustion
- Return buffer and display name `"<stdin>"` for output formatting
- Handle errors gracefully (empty stdin, read errors)

### 6. Implement Multi-File Processing

Refactor the `run_analysis()` function in `file:src/main.rs` (lines 215-294):

- Handle empty `files` vector: read from stdin if no files provided
- Create a new function `process_single_file(file_or_stdin: &FileOrStdin, db: &MagicDatabase, args: &Args)` that evaluates one file and returns a result
- Iterate through all input sources (files or stdin)
- For each source, call `process_single_file()` and immediately output the result
- Continue processing remaining files even if one fails (collect errors but don't abort)
- Track exit code: 0 by default, 3 if any file fails, exit immediately if `--strict` is set

### 7. Update Output Formatting

Modify output logic in `run_analysis()`:

- For text format: use `"{}: {}"` pattern for each file (e.g., `"file.bin: ELF 64-bit"`)
- For JSON format: output JSON Lines format (one JSON object per line) for multiple files
- Handle stdin display: show `"<stdin>"` or `"-"` as the filename
- Ensure each file's output appears on its own line in text mode

### 8. Implement Built-in Rules Flag

Add logic to `run_analysis()`:

- If `--use-builtin` is set, use `MagicDatabase::with_builtin_rules()`
- If `--magic-file` is provided, use that file
- Otherwise, discover and load magic database using updated search order
- Prioritize: `--use-builtin` > `--magic-file` > discovery

### 9. Implement Strict Mode Exit Code Handling

Update exit code logic in `main()` and `run_analysis()`:

- Default behavior: exit 0 even if some files fail (GNU file compatible)
- With `--strict`: exit non-zero (3) if any file fails
- Per-file errors: print to stderr with filename context
- Continue processing remaining files unless `--strict` is set

### 10. Update Validation Logic

Modify validation functions in `file:src/main.rs`:

- Update `validate_arguments()` to allow empty `files` vector (stdin mode)
- Keep `validate_input_file()` for individual file validation
- Add validation to ensure at least one input source (files or stdin)

### 11. Update Tests

Modify tests in `file:src/main.rs` and `file:tests/cli_integration_tests.rs`:

- Update existing tests to use `files: vec![FileOrStdin::File(PathBuf::from("test.bin"))]`
- Add tests for multiple file arguments: `rmagic file1 file2 file3`
- Add tests for stdin input: `echo "data" | rmagic` or `rmagic -`
- Add tests for mixed scenarios: `rmagic file1 - file2`
- Add tests for `--use-builtin` flag
- Add tests for `--strict` flag with success and failure cases
- Add tests for magic file discovery with environment variables
- Add tests for exit codes: 0 (success), 3 (file error), 5 (timeout)

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI as main()
    participant Args as Args::parse()
    participant Discovery as Magic Discovery
    participant DB as MagicDatabase
    participant Processor as process_single_file()
    participant Output as Output Formatter

    User->>CLI: rmagic file1 file2 -
    CLI->>Args: Parse arguments
    Args-->>CLI: files=[file1, file2, stdin]
    
    alt --use-builtin flag set
        CLI->>DB: MagicDatabase::with_builtin_rules()
    else --magic-file provided
        CLI->>DB: MagicDatabase::load_from_file(magic_file)
    else discover magic file
        CLI->>Discovery: get_magic_file_path()
        Discovery->>Discovery: Check MAGIC env var
        Discovery->>Discovery: Check MAGIC_FILE env var
        Discovery->>Discovery: Check text directories/files
        Discovery->>Discovery: Check binary .mgc files
        Discovery->>Discovery: Check CI/dev fallback
        Discovery-->>CLI: magic_file_path
        CLI->>DB: MagicDatabase::load_from_file(magic_file_path)
    end
    
    DB-->>CLI: MagicDatabase instance
    
    loop For each file in files
        alt file is stdin
            CLI->>CLI: read_from_stdin()
            CLI->>Processor: process_single_file(stdin_buffer)
        else regular file
            CLI->>Processor: process_single_file(file)
        end
        
        Processor->>DB: evaluate_file()
        DB-->>Processor: EvaluationResult or Error
        
        alt Success
            Processor-->>CLI: Result
            CLI->>Output: format_output(result)
            Output-->>User: filename: description
        else Error
            Processor-->>CLI: Error
            CLI->>CLI: eprintln!("{}: Error: {}", filename, error)
            alt --strict mode
                CLI-->>User: Exit code 3
            else default mode
                CLI->>CLI: Continue to next file
            end
        end
    end
    
    alt --strict and any error
        CLI-->>User: Exit code 3
    else all succeeded or default mode
        CLI-->>User: Exit code 0
    end
```

## Additional Considerations

**Environment Variables**: Support `MAGIC` and `MAGIC_FILE` environment variables in the magic file discovery logic, checking them before the hardcoded paths. This aligns with GNU `file` command behavior.

**Stdin Buffer Management**: When reading from stdin, use a reasonable buffer size limit (e.g., 1GB matching `FileBuffer::MAX_FILE_SIZE`) to prevent memory exhaustion attacks. Warn if stdin is truncated.

**Output Consistency**: Ensure that when processing multiple files, the output format remains consistent with GNU `file` command behavior, where each line shows `filename: description` in text mode and JSON Lines format in JSON mode.

**Performance**: Process files sequentially rather than in parallel to maintain output order and avoid resource contention, which aligns with GNU `file` command behavior.

**Backward Compatibility**: The changes maintain backward compatibility - existing single-file invocations like `rmagic file.bin` will continue to work without modification.

**Exit Code Semantics**: 
- 0: All files processed successfully
- 3: One or more files failed (with `--strict`, exit immediately on first failure)
- 5: Timeout occurred
- Other codes: Parse errors (4), IO errors (3), etc.

**JSON Lines Format**: For multiple files with `--json`, output one JSON object per line (JSON Lines format), not a single array. This allows streaming processing and is compatible with tools like `jq`.

**Stdin Behavior**: When no files are provided, read from stdin. When `-` is provided as a file argument, read from stdin for that entry. Both behaviors should work identically.

---

Execution Information

Branch: main
Commit: 50b370c

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

The current CLI implementation in file:src/main.rs accepts only a single file argument and lacks stdin support. The magic file discovery logic exists but is hardcoded with platform-specific paths. The output infrastructure (file:src/output/mod.rs, file:src/output/json.rs, file:src/output/text.rs) is well-designed and ready to handle multiple file results. The Args struct uses clap's derive API for argument parsing, making it straightforward to extend for multiple files.

Approach

The implementation will follow the GNU file command conventions: accept multiple file arguments, support stdin via - or when no files are provided, and enhance magic file discovery with environment variable support. The changes will be minimal and focused on the CLI layer in file:src/main.rs, leveraging the existing evaluation and output infrastructure. Each file will be processed independently, with results output immediately to maintain streaming behavior and handle large file lists efficiently.

Implementation Steps

1. Update CLI Argument Structure

Modify the Args struct in file:src/main.rs:

• Change file: PathBuf to files: Vec<PathBuf> to accept multiple file arguments
• Make the files argument optional with #[arg(value_name = "FILE")] and no required = true
• Add a --stdin flag to explicitly read from stdin (optional, for clarity)
• Keep existing --json, --text, and --magic-file options unchanged

2. Enhance Magic File Discovery

Update the default_magic_file_path() function in file:src/main.rs:

• Check for MAGIC environment variable first (standard for GNU file command)
• Check for MAGIC_FILE environment variable as an alternative
• Fall back to existing platform-specific search paths
• Maintain the current CI/CD environment detection logic

3. Implement Stdin Support

Add a new function read_from_stdin() in file:src/main.rs:

• Read all data from std::io::stdin() into a buffer
• Create a temporary file or use in-memory buffer for evaluation
• Return a special filename like "-" or "<stdin>" for output formatting
• Handle errors gracefully (empty stdin, read errors)

4. Implement Multi-File Processing

Refactor the run_analysis() function in file:src/main.rs:

• Determine input sources: if files is empty, read from stdin; if files contains "-", read from stdin for that entry
• Create a new function process_single_file(path: &Path, db: &MagicDatabase, args: &Args) that evaluates one file and returns a result
• Iterate through all input sources (files or stdin)
• For each source, call process_single_file() and immediately output the result
• Continue processing remaining files even if one fails (collect errors but don't abort)
• Return success if at least one file was processed successfully

5. Update Output Formatting

Modify output logic in run_analysis():

• For text format: use existing format!("{}: {}", filename, description) pattern for each file
• For JSON format: collect all results into an array and output once at the end using format_json_output()
• Handle the case where stdin is used: display "-" or "(standard input)" as the filename
• Ensure each file's output appears on its own line in text mode

6. Update Validation Logic

Modify validation functions in file:src/main.rs:

• Update validate_arguments() to allow empty files vector (stdin mode)
• Keep validate_input_file() for individual file validation
• Add validation to ensure stdin is not used multiple times in the same invocation

7. Error Handling Strategy

Update error handling in file:src/main.rs:

• For multiple files: don't exit on first error, continue processing remaining files
• Track failed files and report them to stderr
• Return appropriate exit code: 0 if all succeeded, 1 if some failed, 3 if all failed
• Maintain existing error messages and exit codes for individual file errors

8. Update Tests

Modify tests in file:src/main.rs and file:tests/cli_integration_tests.rs:

• Add tests for multiple file arguments: rmagic file1 file2 file3
• Add tests for stdin input: echo "data" | rmagic or rmagic -
• Add tests for mixed scenarios: rmagic file1 - file2
• Add tests for magic file discovery with environment variables
• Update existing tests to use files: vec![PathBuf::from("test.bin")] instead of file: PathBuf::from("test.bin")

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as main()
    participant Args as Args::parse()
    participant Discovery as Magic Discovery
    participant DB as MagicDatabase
    participant Processor as process_single_file()
    participant Output as Output Formatter

    User->>CLI: rmagic file1 file2 -
    CLI->>Args: Parse arguments
    Args-->>CLI: files=[file1, file2, -]
    
    CLI->>Discovery: get_magic_file_path()
    Discovery->>Discovery: Check MAGIC env var
    Discovery->>Discovery: Check platform paths
    Discovery-->>CLI: magic_file_path
    
    CLI->>DB: load_from_file(magic_file_path)
    DB-->>CLI: MagicDatabase instance
    
    loop For each file in files
        alt file is "-"
            CLI->>CLI: read_from_stdin()
            CLI->>Processor: process_single_file(stdin_data)
        else regular file
            CLI->>Processor: process_single_file(file)
        end
        
        Processor->>DB: evaluate_file()
        DB-->>Processor: EvaluationResult
        Processor-->>CLI: Result
        
        CLI->>Output: format_output(result)
        Output-->>User: filename: description
    end
    
    CLI-->>User: Exit code

Loading

Additional Considerations

Environment Variables: Add support for MAGIC and MAGIC_FILE environment variables in the magic file discovery logic, checking them before the hardcoded paths.

Stdin Buffer Management: When reading from stdin, use a reasonable buffer size limit (e.g., 1GB matching FileBuffer::MAX_FILE_SIZE) to prevent memory exhaustion attacks.

Output Consistency: Ensure that when processing multiple files, the output format remains consistent with GNU file command behavior, where each line shows filename: description.

Performance: Process files sequentially rather than in parallel to maintain output order and avoid resource contention, which aligns with GNU file command behavior.

Backward Compatibility: The changes maintain backward compatibility - existing single-file invocations like rmagic file.bin will continue to work without modification.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current CLI implementation in `file:src/main.rs` accepts only a single file argument and lacks stdin support. The magic file discovery logic exists but is hardcoded with platform-specific paths. The output infrastructure (`file:src/output/mod.rs`, `file:src/output/json.rs`, `file:src/output/text.rs`) is well-designed and ready to handle multiple file results. The `Args` struct uses clap's derive API for argument parsing, making it straightforward to extend for multiple files.

## Approach

The implementation will follow the GNU `file` command conventions: accept multiple file arguments, support stdin via `-` or when no files are provided, and enhance magic file discovery with environment variable support. The changes will be minimal and focused on the CLI layer in `file:src/main.rs`, leveraging the existing evaluation and output infrastructure. Each file will be processed independently, with results output immediately to maintain streaming behavior and handle large file lists efficiently.

## Implementation Steps

### 1. Update CLI Argument Structure

Modify the `Args` struct in `file:src/main.rs`:

- Change `file: PathBuf` to `files: Vec<PathBuf>` to accept multiple file arguments
- Make the `files` argument optional with `#[arg(value_name = "FILE")]` and no `required = true`
- Add a `--stdin` flag to explicitly read from stdin (optional, for clarity)
- Keep existing `--json`, `--text`, and `--magic-file` options unchanged

### 2. Enhance Magic File Discovery

Update the `default_magic_file_path()` function in `file:src/main.rs`:

- Check for `MAGIC` environment variable first (standard for GNU `file` command)
- Check for `MAGIC_FILE` environment variable as an alternative
- Fall back to existing platform-specific search paths
- Maintain the current CI/CD environment detection logic

### 3. Implement Stdin Support

Add a new function `read_from_stdin()` in `file:src/main.rs`:

- Read all data from `std::io::stdin()` into a buffer
- Create a temporary file or use in-memory buffer for evaluation
- Return a special filename like `"-"` or `"<stdin>"` for output formatting
- Handle errors gracefully (empty stdin, read errors)

### 4. Implement Multi-File Processing

Refactor the `run_analysis()` function in `file:src/main.rs`:

- Determine input sources: if `files` is empty, read from stdin; if `files` contains `"-"`, read from stdin for that entry
- Create a new function `process_single_file(path: &Path, db: &MagicDatabase, args: &Args)` that evaluates one file and returns a result
- Iterate through all input sources (files or stdin)
- For each source, call `process_single_file()` and immediately output the result
- Continue processing remaining files even if one fails (collect errors but don't abort)
- Return success if at least one file was processed successfully

### 5. Update Output Formatting

Modify output logic in `run_analysis()`:

- For text format: use existing `format!("{}: {}", filename, description)` pattern for each file
- For JSON format: collect all results into an array and output once at the end using `format_json_output()`
- Handle the case where stdin is used: display `"-"` or `"(standard input)"` as the filename
- Ensure each file's output appears on its own line in text mode

### 6. Update Validation Logic

Modify validation functions in `file:src/main.rs`:

- Update `validate_arguments()` to allow empty `files` vector (stdin mode)
- Keep `validate_input_file()` for individual file validation
- Add validation to ensure stdin is not used multiple times in the same invocation

### 7. Error Handling Strategy

Update error handling in `file:src/main.rs`:

- For multiple files: don't exit on first error, continue processing remaining files
- Track failed files and report them to stderr
- Return appropriate exit code: 0 if all succeeded, 1 if some failed, 3 if all failed
- Maintain existing error messages and exit codes for individual file errors

### 8. Update Tests

Modify tests in `file:src/main.rs` and `file:tests/cli_integration_tests.rs`:

- Add tests for multiple file arguments: `rmagic file1 file2 file3`
- Add tests for stdin input: `echo "data" | rmagic` or `rmagic -`
- Add tests for mixed scenarios: `rmagic file1 - file2`
- Add tests for magic file discovery with environment variables
- Update existing tests to use `files: vec![PathBuf::from("test.bin")]` instead of `file: PathBuf::from("test.bin")`

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI as main()
    participant Args as Args::parse()
    participant Discovery as Magic Discovery
    participant DB as MagicDatabase
    participant Processor as process_single_file()
    participant Output as Output Formatter

    User->>CLI: rmagic file1 file2 -
    CLI->>Args: Parse arguments
    Args-->>CLI: files=[file1, file2, -]
    
    CLI->>Discovery: get_magic_file_path()
    Discovery->>Discovery: Check MAGIC env var
    Discovery->>Discovery: Check platform paths
    Discovery-->>CLI: magic_file_path
    
    CLI->>DB: load_from_file(magic_file_path)
    DB-->>CLI: MagicDatabase instance
    
    loop For each file in files
        alt file is "-"
            CLI->>CLI: read_from_stdin()
            CLI->>Processor: process_single_file(stdin_data)
        else regular file
            CLI->>Processor: process_single_file(file)
        end
        
        Processor->>DB: evaluate_file()
        DB-->>Processor: EvaluationResult
        Processor-->>CLI: Result
        
        CLI->>Output: format_output(result)
        Output-->>User: filename: description
    end
    
    CLI-->>User: Exit code
```

## Additional Considerations

**Environment Variables**: Add support for `MAGIC` and `MAGIC_FILE` environment variables in the magic file discovery logic, checking them before the hardcoded paths.

**Stdin Buffer Management**: When reading from stdin, use a reasonable buffer size limit (e.g., 1GB matching `FileBuffer::MAX_FILE_SIZE`) to prevent memory exhaustion attacks.

**Output Consistency**: Ensure that when processing multiple files, the output format remains consistent with GNU `file` command behavior, where each line shows `filename: description`.

**Performance**: Process files sequentially rather than in parallel to maintain output order and avoid resource contention, which aligns with GNU `file` command behavior.

**Backward Compatibility**: The changes maintain backward compatibility - existing single-file invocations like `rmagic file.bin` will continue to work without modification.

---

Execution Information

Branch: main
Commit: 50b370c

New Plan

Observations

The current CLI implementation in file:src/main.rs accepts only a single file argument and lacks stdin support. The magic file discovery logic exists but has two critical bugs: (1) binary .mgc files are searched FIRST instead of text files/directories, and (2) the create_basic_magic_content() function is dead code that should be removed. The Args struct is missing the --use-builtin and --strict flags required for Phase 1 MVP. The output infrastructure (file:src/output/mod.rs, file:src/output/json.rs, file:src/output/text.rs) is well-designed and ready to handle multiple file results.

Approach

The implementation will follow the GNU file command conventions: accept multiple file arguments via clap-stdin's FileOrStdin type, support stdin input using - as a file argument, reorder magic file discovery to prioritize text files/directories (OpenBSD approach), and add --use-builtin and --strict flags. The changes will be focused on the CLI layer in file:src/main.rs, leveraging the existing evaluation and output infrastructure. Each file will be processed sequentially with immediate output to maintain streaming behavior and handle large file lists efficiently. Exit code handling will default to 0 even if some files fail (GNU file compatible), with --strict mode exiting non-zero on any failure.

Implementation Steps

1. Fix Magic File Search Order (BUG FIX)

Update the default_magic_file_path() function in file:src/main.rs (lines 61-116):

• Reorder candidates to prioritize text files/directories FIRST (OpenBSD approach)
• Place binary .mgc files LAST
• Check environment variables (MAGIC, MAGIC_FILE) before hardcoded paths
• Maintain CI/CD environment detection logic

New order:

1. Environment variables (MAGIC, MAGIC_FILE)
2. Text magic directories (/usr/share/file/magic/Magdir, /usr/share/misc/magic)
3. Text magic files (/etc/magic, /usr/local/share/misc/magic)
4. Binary .mgc files (/usr/share/file/magic.mgc, etc.)
5. Development/CI fallback (third_party/magic.mgc)

2. Remove Dead Code (BUG FIX)

Delete the create_basic_magic_content() function (lines 428-484) and all references to it:

• Remove function definition
• Remove call in download_magic_files() (line 420)
• Update download_magic_files() to return error if magic file not found (no fallback creation)
• Remove --create-magic flag from Args struct (if present)

3. Update CLI Argument Structure

Modify the Args struct in file:src/main.rs (lines 23-39):

• Change file: PathBuf to files: Vec<FileOrStdin> to accept multiple file arguments
• Make the files argument optional with #[arg(value_name = "FILE")]
• Add --use-builtin flag: #[arg(long)] to use built-in rules
• Add --strict flag: #[arg(long)] to exit non-zero on any failure
• Add Rustdoc comments for all new flags
• Keep existing --json, --text, and --magic-file options unchanged

4. Add clap-stdin Dependency

Update Cargo.toml:

• Add clap-stdin = "0.1" to dependencies
• This provides FileOrStdin type for handling - as stdin argument

5. Implement Stdin Support

Add a new function read_from_stdin() in file:src/main.rs:

• Read all data from std::io::stdin() into a buffer
• Respect max_string_length limit (e.g., 1GB) to prevent memory exhaustion
• Return buffer and display name "<stdin>" for output formatting
• Handle errors gracefully (empty stdin, read errors)

6. Implement Multi-File Processing

Refactor the run_analysis() function in file:src/main.rs (lines 215-294):

• Handle empty files vector: read from stdin if no files provided
• Create a new function process_single_file(file_or_stdin: &FileOrStdin, db: &MagicDatabase, args: &Args) that evaluates one file and returns a result
• Iterate through all input sources (files or stdin)
• For each source, call process_single_file() and immediately output the result
• Continue processing remaining files even if one fails (collect errors but don't abort)
• Track exit code: 0 by default, 3 if any file fails, exit immediately if --strict is set

7. Update Output Formatting

Modify output logic in run_analysis():

• For text format: use "{}: {}" pattern for each file (e.g., "file.bin: ELF 64-bit")
• For JSON format: output JSON Lines format (one JSON object per line) for multiple files
• Handle stdin display: show "<stdin>" or "-" as the filename
• Ensure each file's output appears on its own line in text mode

8. Implement Built-in Rules Flag

Add logic to run_analysis():

• If --use-builtin is set, use MagicDatabase::with_builtin_rules()
• If --magic-file is provided, use that file
• Otherwise, discover and load magic database using updated search order
• Prioritize: --use-builtin > --magic-file > discovery

9. Implement Strict Mode Exit Code Handling

Update exit code logic in main() and run_analysis():

• Default behavior: exit 0 even if some files fail (GNU file compatible)
• With --strict: exit non-zero (3) if any file fails
• Per-file errors: print to stderr with filename context
• Continue processing remaining files unless --strict is set

10. Update Validation Logic

Modify validation functions in file:src/main.rs:

• Update validate_arguments() to allow empty files vector (stdin mode)
• Keep validate_input_file() for individual file validation
• Add validation to ensure at least one input source (files or stdin)

11. Update Tests

Modify tests in file:src/main.rs and file:tests/cli_integration_tests.rs:

• Update existing tests to use files: vec![FileOrStdin::File(PathBuf::from("test.bin"))]
• Add tests for multiple file arguments: rmagic file1 file2 file3
• Add tests for stdin input: echo "data" | rmagic or rmagic -
• Add tests for mixed scenarios: rmagic file1 - file2
• Add tests for --use-builtin flag
• Add tests for --strict flag with success and failure cases
• Add tests for magic file discovery with environment variables
• Add tests for exit codes: 0 (success), 3 (file error), 5 (timeout)

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as main()
    participant Args as Args::parse()
    participant Discovery as Magic Discovery
    participant DB as MagicDatabase
    participant Processor as process_single_file()
    participant Output as Output Formatter

    User->>CLI: rmagic file1 file2 -
    CLI->>Args: Parse arguments
    Args-->>CLI: files=[file1, file2, stdin]
    
    alt --use-builtin flag set
        CLI->>DB: MagicDatabase::with_builtin_rules()
    else --magic-file provided
        CLI->>DB: MagicDatabase::load_from_file(magic_file)
    else discover magic file
        CLI->>Discovery: get_magic_file_path()
        Discovery->>Discovery: Check MAGIC env var
        Discovery->>Discovery: Check MAGIC_FILE env var
        Discovery->>Discovery: Check text directories/files
        Discovery->>Discovery: Check binary .mgc files
        Discovery->>Discovery: Check CI/dev fallback
        Discovery-->>CLI: magic_file_path
        CLI->>DB: MagicDatabase::load_from_file(magic_file_path)
    end
    
    DB-->>CLI: MagicDatabase instance
    
    loop For each file in files
        alt file is stdin
            CLI->>CLI: read_from_stdin()
            CLI->>Processor: process_single_file(stdin_buffer)
        else regular file
            CLI->>Processor: process_single_file(file)
        end
        
        Processor->>DB: evaluate_file()
        DB-->>Processor: EvaluationResult or Error
        
        alt Success
            Processor-->>CLI: Result
            CLI->>Output: format_output(result)
            Output-->>User: filename: description
        else Error
            Processor-->>CLI: Error
            CLI->>CLI: eprintln!("{}: Error: {}", filename, error)
            alt --strict mode
                CLI-->>User: Exit code 3
            else default mode
                CLI->>CLI: Continue to next file
            end
        end
    end
    
    alt --strict and any error
        CLI-->>User: Exit code 3
    else all succeeded or default mode
        CLI-->>User: Exit code 0
    end

Loading

Additional Considerations

Environment Variables: Support MAGIC and MAGIC_FILE environment variables in the magic file discovery logic, checking them before the hardcoded paths. This aligns with GNU file command behavior.

Stdin Buffer Management: When reading from stdin, use a reasonable buffer size limit (e.g., 1GB matching FileBuffer::MAX_FILE_SIZE) to prevent memory exhaustion attacks. Warn if stdin is truncated.

Output Consistency: Ensure that when processing multiple files, the output format remains consistent with GNU file command behavior, where each line shows filename: description in text mode and JSON Lines format in JSON mode.

Performance: Process files sequentially rather than in parallel to maintain output order and avoid resource contention, which aligns with GNU file command behavior.

Backward Compatibility: The changes maintain backward compatibility - existing single-file invocations like rmagic file.bin will continue to work without modification.

Exit Code Semantics:

• 0: All files processed successfully
• 3: One or more files failed (with --strict, exit immediately on first failure)
• 5: Timeout occurred
• Other codes: Parse errors (4), IO errors (3), etc.

JSON Lines Format: For multiple files with --json, output one JSON object per line (JSON Lines format), not a single array. This allows streaming processing and is compatible with tools like jq.

Stdin Behavior: When no files are provided, read from stdin. When - is provided as a file argument, read from stdin for that entry. Both behaviors should work identically.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current CLI implementation in `file:src/main.rs` accepts only a single file argument and lacks stdin support. The magic file discovery logic exists but has two critical bugs: (1) binary .mgc files are searched FIRST instead of text files/directories, and (2) the `create_basic_magic_content()` function is dead code that should be removed. The `Args` struct is missing the `--use-builtin` and `--strict` flags required for Phase 1 MVP. The output infrastructure (`file:src/output/mod.rs`, `file:src/output/json.rs`, `file:src/output/text.rs`) is well-designed and ready to handle multiple file results.

## Approach

The implementation will follow the GNU `file` command conventions: accept multiple file arguments via clap-stdin's `FileOrStdin` type, support stdin input using `-` as a file argument, reorder magic file discovery to prioritize text files/directories (OpenBSD approach), and add `--use-builtin` and `--strict` flags. The changes will be focused on the CLI layer in `file:src/main.rs`, leveraging the existing evaluation and output infrastructure. Each file will be processed sequentially with immediate output to maintain streaming behavior and handle large file lists efficiently. Exit code handling will default to 0 even if some files fail (GNU file compatible), with `--strict` mode exiting non-zero on any failure.

## Implementation Steps

### 1. Fix Magic File Search Order (BUG FIX)

Update the `default_magic_file_path()` function in `file:src/main.rs` (lines 61-116):

- Reorder candidates to prioritize text files/directories FIRST (OpenBSD approach)
- Place binary .mgc files LAST
- Check environment variables (`MAGIC`, `MAGIC_FILE`) before hardcoded paths
- Maintain CI/CD environment detection logic

New order:
1. Environment variables (`MAGIC`, `MAGIC_FILE`)
2. Text magic directories (`/usr/share/file/magic/Magdir`, `/usr/share/misc/magic`)
3. Text magic files (`/etc/magic`, `/usr/local/share/misc/magic`)
4. Binary .mgc files (`/usr/share/file/magic.mgc`, etc.)
5. Development/CI fallback (`third_party/magic.mgc`)

### 2. Remove Dead Code (BUG FIX)

Delete the `create_basic_magic_content()` function (lines 428-484) and all references to it:

- Remove function definition
- Remove call in `download_magic_files()` (line 420)
- Update `download_magic_files()` to return error if magic file not found (no fallback creation)
- Remove `--create-magic` flag from `Args` struct (if present)

### 3. Update CLI Argument Structure

Modify the `Args` struct in `file:src/main.rs` (lines 23-39):

- Change `file: PathBuf` to `files: Vec<FileOrStdin>` to accept multiple file arguments
- Make the `files` argument optional with `#[arg(value_name = "FILE")]`
- Add `--use-builtin` flag: `#[arg(long)]` to use built-in rules
- Add `--strict` flag: `#[arg(long)]` to exit non-zero on any failure
- Add Rustdoc comments for all new flags
- Keep existing `--json`, `--text`, and `--magic-file` options unchanged

### 4. Add clap-stdin Dependency

Update `Cargo.toml`:

- Add `clap-stdin = "0.1"` to dependencies
- This provides `FileOrStdin` type for handling `-` as stdin argument

### 5. Implement Stdin Support

Add a new function `read_from_stdin()` in `file:src/main.rs`:

- Read all data from `std::io::stdin()` into a buffer
- Respect `max_string_length` limit (e.g., 1GB) to prevent memory exhaustion
- Return buffer and display name `"<stdin>"` for output formatting
- Handle errors gracefully (empty stdin, read errors)

### 6. Implement Multi-File Processing

Refactor the `run_analysis()` function in `file:src/main.rs` (lines 215-294):

- Handle empty `files` vector: read from stdin if no files provided
- Create a new function `process_single_file(file_or_stdin: &FileOrStdin, db: &MagicDatabase, args: &Args)` that evaluates one file and returns a result
- Iterate through all input sources (files or stdin)
- For each source, call `process_single_file()` and immediately output the result
- Continue processing remaining files even if one fails (collect errors but don't abort)
- Track exit code: 0 by default, 3 if any file fails, exit immediately if `--strict` is set

### 7. Update Output Formatting

Modify output logic in `run_analysis()`:

- For text format: use `"{}: {}"` pattern for each file (e.g., `"file.bin: ELF 64-bit"`)
- For JSON format: output JSON Lines format (one JSON object per line) for multiple files
- Handle stdin display: show `"<stdin>"` or `"-"` as the filename
- Ensure each file's output appears on its own line in text mode

### 8. Implement Built-in Rules Flag

Add logic to `run_analysis()`:

- If `--use-builtin` is set, use `MagicDatabase::with_builtin_rules()`
- If `--magic-file` is provided, use that file
- Otherwise, discover and load magic database using updated search order
- Prioritize: `--use-builtin` > `--magic-file` > discovery

### 9. Implement Strict Mode Exit Code Handling

Update exit code logic in `main()` and `run_analysis()`:

- Default behavior: exit 0 even if some files fail (GNU file compatible)
- With `--strict`: exit non-zero (3) if any file fails
- Per-file errors: print to stderr with filename context
- Continue processing remaining files unless `--strict` is set

### 10. Update Validation Logic

Modify validation functions in `file:src/main.rs`:

- Update `validate_arguments()` to allow empty `files` vector (stdin mode)
- Keep `validate_input_file()` for individual file validation
- Add validation to ensure at least one input source (files or stdin)

### 11. Update Tests

Modify tests in `file:src/main.rs` and `file:tests/cli_integration_tests.rs`:

- Update existing tests to use `files: vec![FileOrStdin::File(PathBuf::from("test.bin"))]`
- Add tests for multiple file arguments: `rmagic file1 file2 file3`
- Add tests for stdin input: `echo "data" | rmagic` or `rmagic -`
- Add tests for mixed scenarios: `rmagic file1 - file2`
- Add tests for `--use-builtin` flag
- Add tests for `--strict` flag with success and failure cases
- Add tests for magic file discovery with environment variables
- Add tests for exit codes: 0 (success), 3 (file error), 5 (timeout)

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI as main()
    participant Args as Args::parse()
    participant Discovery as Magic Discovery
    participant DB as MagicDatabase
    participant Processor as process_single_file()
    participant Output as Output Formatter

    User->>CLI: rmagic file1 file2 -
    CLI->>Args: Parse arguments
    Args-->>CLI: files=[file1, file2, stdin]
    
    alt --use-builtin flag set
        CLI->>DB: MagicDatabase::with_builtin_rules()
    else --magic-file provided
        CLI->>DB: MagicDatabase::load_from_file(magic_file)
    else discover magic file
        CLI->>Discovery: get_magic_file_path()
        Discovery->>Discovery: Check MAGIC env var
        Discovery->>Discovery: Check MAGIC_FILE env var
        Discovery->>Discovery: Check text directories/files
        Discovery->>Discovery: Check binary .mgc files
        Discovery->>Discovery: Check CI/dev fallback
        Discovery-->>CLI: magic_file_path
        CLI->>DB: MagicDatabase::load_from_file(magic_file_path)
    end
    
    DB-->>CLI: MagicDatabase instance
    
    loop For each file in files
        alt file is stdin
            CLI->>CLI: read_from_stdin()
            CLI->>Processor: process_single_file(stdin_buffer)
        else regular file
            CLI->>Processor: process_single_file(file)
        end
        
        Processor->>DB: evaluate_file()
        DB-->>Processor: EvaluationResult or Error
        
        alt Success
            Processor-->>CLI: Result
            CLI->>Output: format_output(result)
            Output-->>User: filename: description
        else Error
            Processor-->>CLI: Error
            CLI->>CLI: eprintln!("{}: Error: {}", filename, error)
            alt --strict mode
                CLI-->>User: Exit code 3
            else default mode
                CLI->>CLI: Continue to next file
            end
        end
    end
    
    alt --strict and any error
        CLI-->>User: Exit code 3
    else all succeeded or default mode
        CLI-->>User: Exit code 0
    end
```

## Additional Considerations

**Environment Variables**: Support `MAGIC` and `MAGIC_FILE` environment variables in the magic file discovery logic, checking them before the hardcoded paths. This aligns with GNU `file` command behavior.

**Stdin Buffer Management**: When reading from stdin, use a reasonable buffer size limit (e.g., 1GB matching `FileBuffer::MAX_FILE_SIZE`) to prevent memory exhaustion attacks. Warn if stdin is truncated.

**Output Consistency**: Ensure that when processing multiple files, the output format remains consistent with GNU `file` command behavior, where each line shows `filename: description` in text mode and JSON Lines format in JSON mode.

**Performance**: Process files sequentially rather than in parallel to maintain output order and avoid resource contention, which aligns with GNU `file` command behavior.

**Backward Compatibility**: The changes maintain backward compatibility - existing single-file invocations like `rmagic file.bin` will continue to work without modification.

**Exit Code Semantics**: 
- 0: All files processed successfully
- 3: One or more files failed (with `--strict`, exit immediately on first failure)
- 5: Timeout occurred
- Other codes: Parse errors (4), IO errors (3), etc.

**JSON Lines Format**: For multiple files with `--json`, output one JSON object per line (JSON Lines format), not a single array. This allows streaming processing and is compatible with tools like `jq`.

**Stdin Behavior**: When no files are provided, read from stdin. When `-` is provided as a file argument, read from stdin for that entry. Both behaviors should work identically.

---

Execution Information

Branch: main
Commit: 50b370c

[unclesp1d3r]

@coderabbitai Assign the proper labels and other metadata to this issue

[coderabbitai]

🧩 Analysis chain

@unclesp1d3r, I'll check the available labels in the repository and assign appropriate ones to this issue.

---

🏁 Script executed:

#!/bin/bash

# First, let's see what labels are available in the repository
echo "=== Available Labels ==="
gh label list --repo EvilBit-Labs/libmagic-rs --limit 100

echo -e "\n=== Current Issue Details ==="
# Check the current state of issue `#18`
gh issue view 18 --repo EvilBit-Labs/libmagic-rs --json number,title,labels,assignees,milestone,state

echo -e "\n=== Issue Body (first 500 chars) ==="
# Get a preview of the issue body to understand the content
gh issue view 18 --repo EvilBit-Labs/libmagic-rs --json body --jq '.body' | head -c 500

Length of output: 1753

---

🏁 Script executed:

#!/bin/bash

# Based on the issue content (CLI enhancements, bug fixes, new features),
# let's add appropriate labels
echo "=== Adding labels to issue `#18` ==="

# Add labels - adjust based on what's available in the repo
# Common labels that might exist: enhancement, bug, CLI, feature, good first issue, etc.
gh issue edit 18 --repo EvilBit-Labs/libmagic-rs \
  --add-label "enhancement" \
  --add-label "CLI" \
  --add-label "feature" \
  2>&1 || echo "Some labels might not exist in the repository"

# Check if there's a bug label since there are bug fixes mentioned
gh issue edit 18 --repo EvilBit-Labs/libmagic-rs \
  --add-label "bug" \
  2>&1 || echo "Bug label might not exist"

# Try to add priority or phase labels if they exist
gh issue edit 18 --repo EvilBit-Labs/libmagic-rs \
  --add-label "priority: high" \
  2>&1 || echo "Priority label might not exist"

echo -e "\n=== Updated Issue Details ==="
gh issue view 18 --repo EvilBit-Labs/libmagic-rs --json labels,assignees

Length of output: 570

---

🏁 Script executed:

#!/bin/bash

echo "=== Adding appropriate labels to issue `#18` ==="
# Add the correct labels that exist in the repository
gh issue edit 18 --repo EvilBit-Labs/libmagic-rs \
  --add-label "enhancement" \
  --add-label "cli" \
  --add-label "io"

echo -e "\n=== Setting assignee ==="
# Set assignee to unclesp1d3r since they're the one requesting this
gh issue edit 18 --repo EvilBit-Labs/libmagic-rs \
  --add-assignee "unclesp1d3r"

echo -e "\n=== Final Issue Details ==="
gh issue view 18 --repo EvilBit-Labs/libmagic-rs --json number,title,labels,assignees --jq '{number, title, labels: [.labels[].name], assignees: [.assignees[].login]}'

Length of output: 360

---

@unclesp1d3r, I've successfully assigned the appropriate labels and metadata to issue #18:

Labels added:

• bug - For the magic file search order fix and dead code removal
• enhancement - For the new features being added
• cli - This is a CLI-focused enhancement
• io - Covers file I/O and stdin operations

Assignee: Set to you (unclesp1d3r)

The issue is now properly categorized and ready for work! 🎯