# QFU - Quadarax Filesystem Utility

A command-line utility for filesystem operations and file manipulations built on .NET 9.0.

## Overview

QFU is a powerful filesystem utility that provides efficient file operations through a modular command-based architecture. The tool is designed for developers and system administrators who need reliable file manipulation capabilities with robust error handling and flexible input options.

### Key Features

- **File Cloning**: Clone source files to multiple destinations with various options
- **Flexible Input Methods**: Support for direct file specification or file list input
- **Path Management**: Automatic directory creation when needed
- **Force Operations**: Override existing files when necessary
- **Robust Error Handling**: Comprehensive validation and error reporting
- **Modular Architecture**: Extensible command and aspect-based design

## Architecture

The application follows a clean modular architecture:

- **Commands**: Core operations (currently `clone`)
- **Aspects**: Reusable functionality components (Source, Files, List, Force)
- **Base Classes**: Shared functionality and abstractions
- **Dependency Injection**: Uses `System.IO.Abstractions` for testable file operations

## Installation

### Prerequisites

- .NET 9.0 Runtime
- Windows, Linux, or macOS

### Build from Source

```bash
git clone <repository-url>
cd qfu
dotnet build --configuration Release
dotnet publish --configuration Release --self-contained
```

## Usage

### Basic Syntax

```
qfu <command> [arguments] [options]
```

### Commands

#### Clone Command

Clone a source file to one or more destination files.

**Syntax:**
```
qfu clone <source_file> <target_files> [options]
```

**Arguments:**
- `source_file`: Path to the source file to clone
- `target_files`: Pipe-separated list of target file paths (`file1.txt|file2.txt|file3.txt`)

**Options:**
- `-pe` or `-path_ensure`: Create destination directories if they don't exist
- `-force`: Overwrite existing destination files
- `-list`: Treat the first target file as a text file containing a list of destination paths (one per line)

### Examples

#### Basic File Cloning
```bash
# Clone a file to multiple destinations
qfu clone source.txt "backup1.txt|backup2.txt|backup3.txt"
```

#### Clone with Path Creation
```bash
# Clone and create destination directories if needed
qfu clone template.config "configs/dev.config|configs/staging.config|configs/prod.config" -pe
```

#### Force Overwrite Existing Files
```bash
# Overwrite existing destination files
qfu clone master.template "project1/config.xml|project2/config.xml" -force -pe
```

#### Using File Lists
```bash
# Create a file list first
echo "backup/file1.txt" > targets.txt
echo "backup/file2.txt" >> targets.txt
echo "backup/file3.txt" >> targets.txt

# Use the list file for cloning
qfu clone source.txt targets.txt -list -pe
```

#### Complex Example
```bash
# Clone with all options
qfu clone template.cs "src/Class1.cs|src/Class2.cs|tests/TestClass.cs" -force -pe
```

### Return Codes

- `0`: Success - all operations completed successfully
- `Non-zero`: Failure - check console output for specific error details

### Output Format

QFU provides detailed progress information:
- Operation summary at start
- Individual file operation status
- Final success/failure count
- Detailed error messages for failed operations

Example output:
```
Will be cloning file 'source.txt' to 3 files (with force)...
[1] Cloned 'source.txt' to 'dest1.txt' successfully.
[2] File 'dest2.txt' already exists. Skipping clone operation.
[3] Cloned 'source.txt' to 'dest3.txt' successfully.
Successfully cloned: 2 of 3 files.
```

## Error Handling

QFU provides comprehensive error handling:

- **Source Validation**: Verifies source file exists before operation
- **Destination Validation**: Checks for existing files (unless `--force` used)
- **Path Validation**: Ensures destination paths are valid
- **Permission Checking**: Reports access denied errors
- **List File Validation**: Validates list files when using `-list` option

## Development

### Project Structure

```
qfu/
├── Commands/
│   ├── BaseCmd.cs          # Base command functionality
│   ├── CloneCmd.cs         # Clone command implementation
│   └── Aspects/
│       ├── FilesAspect.cs  # File handling logic
│       ├── ForceAspect.cs  # Force operation logic
│       ├── ListAspect.cs   # List file processing
│       └── SourceAspect.cs # Source file validation
├── QfuCommandContext.cs    # Command execution context
├── QfuEngineContext.cs     # Engine context
└── Program.cs              # Application entry point
```

### Adding New Commands

1. Create a new command class inheriting from `BaseCmd`
2. Implement required abstract members
3. Add `[CommandDefinition]` attribute
4. Define command-specific aspects if needed

### Testing

The project uses `System.IO.Abstractions` for testable file operations. Mock the `IFileSystem` interface for unit testing.

## License

Copyright © 2025 Quadarax

## Support

For issues and feature requests, please visit: https://quadarax.com/qfu

---

**Version**: 1.0.0  
**Target Framework**: .NET 9.0  
**Package Tags**: FILE, UTILITY