Universal Toolkit

https://github.com/0langa/universal-toolkit
Admin
A modern C++ toolkit providing five file and storage management utilities (find, duplicate...
Tokens:10,005
Snippets:76
Trust Score:1.9
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Building from Source

Source: https://context7.com/0langa/universal-toolkit/llms.txt

Instructions for building the Universal Toolkit from source using CMake on Linux and Windows.

```APIDOC
## Building from Source

### Description
Instructions for building the Universal Toolkit from source using CMake on Linux and Windows.

### Method
N/A (Build commands)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```bash
# Linux (GCC/Clang)
cmake --preset linux-debug
cmake --build --preset linux-debug-build
ctest --preset linux-test --output-on-failure

# Windows (MSVC)
cmake --preset x64-debug
cmake --build --preset x64-debug-build
ctest --preset x64-test --output-on-failure
```

### Response
N/A (Build process output)

### Response Example
N/A
```

--------------------------------

### Build and Test Universal-Toolkit (Bash)

Source: https://context7.com/0langa/universal-toolkit/llms.txt

Provides build and test commands for the universal-toolkit using CMake presets for both Linux (GCC/Clang) and Windows (MSVC) environments. It demonstrates how to configure debug builds, compile the project, and run tests with failure output enabled.

```bash
# Linux (GCC/Clang)
cmake --preset linux-debug
cmake --build --preset linux-debug-build
ctest --preset linux-test --output-on-failure

# Windows (MSVC)
cmake --preset x64-debug
cmake --build --preset x64-debug-build
ctest --preset x64-test --output-on-failure

```

--------------------------------

### CLI File Search and Management

Source: https://context7.com/0langa/universal-toolkit/llms.txt

Demonstrates the command-line interface for searching, analyzing, and organizing files. These commands support various filters like size, patterns, and recursive flags.

```bash
utk find ~/Documents --ext .pdf
utk find /var/log --pattern "*.log" --no-recursive
utk find . --min-size 1048576
utk find ~/data --pattern "report_*.csv" --min-size 10000
utk dupes ~/Downloads
utk dupes ~/Pictures --min-size 4096
utk analyze ~/Projects
utk analyze /home --top 20
utk organize ~/Downloads ~/Sorted --strategy ext --dry-run
utk organize ~/Photos ~/Archive --strategy yearmonth --copy
utk organize ~/Documents ~/ByYear --strategy year
utk large /home
utk large /var --threshold 52428800 --max 10
```

--------------------------------

### Configure Root CMake Project

Source: https://github.com/0langa/universal-toolkit/blob/main/CMakeLists.txt

Initializes the CMake project, sets C++20 standards, and configures MSVC debug information formats. It serves as the entry point for building the toolkit and managing subdirectories.

```cmake
cmake_minimum_required(VERSION 3.20)

if(POLICY CMP0141)
    cmake_policy(SET CMP0141 NEW)
    set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT
        "$<IF:$<AND:$<C_COMPILER_ID:MSVC>,$<CXX_COMPILER_ID:MSVC>>,$<$<CONFIG:Debug,RelWithDebInfo>:EditAndContinue>,$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>>")
endif()

project("Universal Toolkit"
    VERSION      0.2.0
    DESCRIPTION  "A modern C++ toolkit for file and storage management"
    LANGUAGES    CXX
)

set(CMAKE_CXX_STANDARD          20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS        OFF)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

add_subdirectory(src/modules)
add_subdirectory(src/app)

option(BUILD_TESTING "Build test executables" ON)
if(BUILD_TESTING)
    enable_testing()
    add_subdirectory(tests)
endif()
```

--------------------------------

### Universal Toolkit CLI - Organize

Source: https://context7.com/0langa/universal-toolkit/llms.txt

The `utk organize` command automatically moves or copies files into subdirectories based on specified organization strategies like extension or modification date.

```APIDOC
## CLI: utk organize - Automatic File Organization

### Description
Moves or copies files into organized subdirectories based on extension or modification date.

### Usage
```bash
utk organize [SOURCE_DIR] [DEST_DIR] [OPTIONS]
```

### Options
- `--strategy <ext|year|month|yearmonth>`: Organization strategy.
- `--dry-run`: Perform a trial run without moving/copying files.
- `--copy`: Copy files instead of moving them.

### Examples
```bash
# Preview organization by extension (dry run)
utk organize ~/Downloads ~/Sorted --strategy ext --dry-run

# Organize photos by year-month, copying instead of moving
utk organize ~/Photos ~/Archive --strategy yearmonth --copy

# Organize by year only
utk organize ~/Documents ~/ByYear --strategy year
```
```

--------------------------------

### Universal Toolkit CLI - Analyze

Source: https://context7.com/0langa/universal-toolkit/llms.txt

The `utk analyze` command generates a detailed storage report for a given directory, including size breakdowns and lists of large files/directories.

```APIDOC
## CLI: utk analyze - Storage Analysis

### Description
Generates a comprehensive storage report including total size, per-extension breakdown, top N largest files/directories, and disk space information.

### Usage
```bash
utk analyze [DIRECTORY] [OPTIONS]
```

### Options
- `--top <N>`: Display the top N largest files or directories (default 10).

### Examples
```bash
# Analyze storage with default settings (top 10)
utk analyze ~/Projects

# Show top 20 largest files
utk analyze /home --top 20
```
```

--------------------------------

### Configure and Register Unit Tests with CMake

Source: https://github.com/0langa/universal-toolkit/blob/main/tests/CMakeLists.txt

This script enables testing, defines a list of source files, and iterates through them to create executables. It sets include directories, links necessary libraries, enforces C++20 standards, and applies compiler-specific warning flags before adding each test to the CTest suite.

```cmake
enable_testing()

set(TEST_SOURCES
    test_file_finder.cpp
    test_duplicate_finder.cpp
    test_storage_analyzer.cpp
    test_file_organizer.cpp
    test_large_file_finder.cpp
)

foreach(src ${TEST_SOURCES})
    get_filename_component(test_name ${src} NAME_WE)
    add_executable(${test_name} ${src})
    target_include_directories(${test_name} PRIVATE
        ${CMAKE_CURRENT_SOURCE_DIR}
        ${PROJECT_SOURCE_DIR}/include
    )
    target_link_libraries(${test_name} PRIVATE toolkit_modules)
    target_compile_features(${test_name} PRIVATE cxx_std_20)
    if(UNIX)
        target_compile_options(${test_name} PRIVATE -Wall -Wextra)
    elseif(MSVC)
        target_compile_options(${test_name} PRIVATE /W4)
    endif()
    add_test(NAME ${test_name} COMMAND ${test_name})
endforeach()
```

--------------------------------

### Analyze Disk Usage with StorageAnalyzer (C++)

Source: https://context7.com/0langa/universal-toolkit/llms.txt

Computes comprehensive storage statistics for a given directory, including total size, per-extension breakdown, top files/directories, and filesystem space information. It requires the 'toolkit/storage_analyzer.hpp' header and outputs detailed report structures. Options can be configured for recursive scanning, skipping hidden files, and specifying the number of top entries.

```cpp
#include "toolkit/storage_analyzer.hpp"
#include <iostream>

using namespace toolkit;

int main() {
    StorageAnalyzerOptions opts;
    opts.recursive = true;
    opts.skip_hidden = false;
    opts.top_n = 10;  // top 10 files and directories

    StorageReport report = StorageAnalyzer::analyze("/home/user/Projects", opts);

    std::cout << "Root: " << report.root.string() << "\n";
    std::cout << "Total: " << StorageReport::human_readable(report.total_bytes) << "\n";
    std::cout << "Files: " << report.total_files << "\n";
    std::cout << "Directories: " << report.total_dirs << "\n\n";

    // Per-extension breakdown
    std::cout << "By extension:\n";
    for (const auto& [ext, bytes] : report.by_extension) {
        std::cout << "  " << ext << ": "
                  << StorageReport::human_readable(bytes) << "\n";
    }

    // Top files
    std::cout << "\nTop files:\n";
    for (const auto& entry : report.top_files) {
        std::cout << "  " << StorageReport::human_readable(entry.bytes)
                  << "  " << entry.path.string() << "\n";
    }

    // Quick directory size (fast path)
    auto dirSize = StorageAnalyzer::directory_size("/var/log");

    // Disk space info
    auto [available, capacity] = StorageAnalyzer::disk_space("/");
    std::cout << "\nDisk: " << StorageReport::human_readable(available)
              << " / " << StorageReport::human_readable(capacity) << " free\n";

    return 0;
}

```

--------------------------------

### Universal Toolkit CLI - Find

Source: https://context7.com/0langa/universal-toolkit/llms.txt

The `utk find` command recursively searches directory trees for files matching specified patterns or extensions, with options for size filtering and recursion control.

```APIDOC
## CLI: utk find - Recursive File Search

### Description
Searches a directory tree for files matching a glob pattern or extension filter. Supports wildcard patterns (`*` and `?`), size filtering, and recursive/non-recursive modes.

### Usage
```bash
utk find [DIRECTORY] [OPTIONS]
```

### Options
- `--ext <.ext1,.ext2>`: Filter by file extension.
- `--pattern <glob>`: Filter by glob pattern.
- `--min-size <bytes>`: Minimum file size in bytes.
- `--max-size <bytes>`: Maximum file size in bytes.
- `--recursive` / `--no-recursive`: Control recursion (default is recursive).

### Examples
```bash
# Find all PDF files recursively
utk find ~/Documents --ext .pdf

# Find files matching a glob pattern (non-recursive)
utk find /var/log --pattern "*.log" --no-recursive

# Find files larger than 1 MiB
utk find . --min-size 1048576

# Combined: find large CSV files
utk find ~/data --pattern "report_*.csv" --min-size 10000
```
```

--------------------------------

### Configure CMake Executable and Build Settings

Source: https://github.com/0langa/universal-toolkit/blob/main/src/app/CMakeLists.txt

Defines the utk executable, links the toolkit_modules library, and sets the C++20 standard. It also applies platform-specific compiler flags for GCC/Clang and MSVC to ensure code quality.

```cmake
add_executable(utk main.cpp)
target_link_libraries(utk PRIVATE toolkit_modules)
target_compile_features(utk PRIVATE cxx_std_20)

if(UNIX)
    target_compile_options(utk PRIVATE -Wall -Wextra -Wpedantic)
elseif(MSVC)
    target_compile_options(utk PRIVATE /W4)
endif()
```

--------------------------------

### Organize Files with FileOrganizer (C++)

Source: https://context7.com/0langa/universal-toolkit/llms.txt

Automatically moves or copies files into organized subdirectories based on extension or modification date. It supports dry-run mode for previewing operations and can specify a folder for files without extensions. The function returns a list of operations performed or planned, including any errors encountered. Dependencies include 'toolkit/file_organizer.hpp'.

```cpp
#include "toolkit/file_organizer.hpp"
#include <iostream>

using namespace toolkit;

int main() {
    FileOrganizerOptions opts;
    opts.strategy = OrganizeStrategy::ByExtension;  // or ByYear, ByYearMonth
    opts.copy_instead_of_move = false;  // move files
    opts.dry_run = true;                // preview first
    opts.overwrite_existing = false;
    opts.no_extension_folder = "other"; // folder for files without extension

    auto operations = FileOrganizer::organize(
        "/home/user/Downloads",
        "/home/user/Sorted",
        opts
    );

    std::cout << (opts.dry_run ? "[DRY RUN] " : "")
              << "Operations: " << operations.size() << "\n\n";

    for (const auto& op : operations) {
        std::cout << op.source.filename().string()
                  << " -> " << op.destination.string();
        if (!op.error.empty()) {
            std::cout << " [ERROR: " << op.error << "]";
        }
        if (op.was_executed) {
            std::cout << " [DONE]";
        }
        std::cout << "\n";
    }

    // Execute for real after preview
    opts.dry_run = false;
    auto results = FileOrganizer::organize(
        "/home/user/Downloads",
        "/home/user/Sorted",
        opts
    );

    return 0;
}

```

--------------------------------

### Universal Toolkit CLI - Large

Source: https://context7.com/0langa/universal-toolkit/llms.txt

The `utk large` command finds files that exceed a specified size threshold, sorted by size in descending order.

```APIDOC
## CLI: utk large - Large File Discovery

### Description
Finds files exceeding a size threshold, sorted by size descending.

### Usage
```bash
utk large [DIRECTORY] [OPTIONS]
```

### Options
- `--threshold <bytes>`: Minimum file size in bytes (default 100 MiB).
- `--max <N>`: Limit the output to the top N files.

### Examples
```bash
# Find files >= 100 MiB (default threshold)
utk large /home

# Custom threshold: files >= 50 MiB, limit to top 10
utk large /var --threshold 52428800 --max 10
```
```

--------------------------------

### Universal Toolkit CLI - Dupes

Source: https://context7.com/0langa/universal-toolkit/llms.txt

The `utk dupes` command identifies duplicate files within a directory by comparing their content hashes, reporting on wasted space.

```APIDOC
## CLI: utk dupes - Duplicate File Detection

### Description
Identifies duplicate files by content hash (FNV-1a 64-bit). Groups identical files and reports wasted space statistics.

### Usage
```bash
utk dupes [DIRECTORY] [OPTIONS]
```

### Options
- `--min-size <bytes>`: Ignore files smaller than this size (default 0).
- `--recursive` / `--no-recursive`: Control recursion (default is recursive).

### Examples
```bash
# Scan Downloads folder for duplicates
utk dupes ~/Downloads

# Ignore very small files (e.g., < 4KB)
utk dupes ~/Pictures --min-size 4096
```
```

--------------------------------

### StorageAnalyzer - Disk Usage Analysis

Source: https://context7.com/0langa/universal-toolkit/llms.txt

Analyzes disk usage by computing total size, per-extension breakdown, top files/directories, and filesystem space information. Supports recursive analysis and options to skip hidden files.

```APIDOC
## StorageAnalyzer - Disk Usage Analysis

### Description
Computes comprehensive storage statistics including total size, per-extension breakdown, top files/directories, and filesystem space info.

### Method
N/A (This is a C++ library usage example)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **path** (string) - Required - The root directory to analyze.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```cpp
#include "toolkit/storage_analyzer.hpp"
#include <iostream>

using namespace toolkit;

int main() {
    StorageAnalyzerOptions opts;
    opts.recursive = true;
    opts.skip_hidden = false;
    opts.top_n = 10;

    StorageReport report = StorageAnalyzer::analyze("/home/user/Projects", opts);

    std::cout << "Root: " << report.root.string() << "\n";
    std::cout << "Total: " << StorageReport::human_readable(report.total_bytes) << "\n";
    std::cout << "Files: " << report.total_files << "\n";
    std::cout << "Directories: " << report.total_dirs << "\n\n";

    std::cout << "By extension:\n";
    for (const auto& [ext, bytes] : report.by_extension) {
        std::cout << "  " << ext << ": "
                  << StorageReport::human_readable(bytes) << "\n";
    }

    std::cout << "\nTop files:\n";
    for (const auto& entry : report.top_files) {
        std::cout << "  " << StorageReport::human_readable(entry.bytes)
                  << "  " << entry.path.string() << "\n";
    }

    auto dirSize = StorageAnalyzer::directory_size("/var/log");

    auto [available, capacity] = StorageAnalyzer::disk_space("/");
    std::cout << "\nDisk: " << StorageReport::human_readable(available)
              << " / " << StorageReport::human_readable(capacity) << " free\n";

    return 0;
}
```

### Response
#### Success Response (200)
- **report** (StorageReport) - An object containing detailed storage analysis results.

#### Response Example
```json
{
  "root": "/home/user/Projects",
  "total_bytes": 1234567890,
  "total_files": 500,
  "total_dirs": 50,
  "by_extension": {
    "cpp": 800000000,
    "h": 100000000,
    "txt": 50000000
  },
  "top_files": [
    {"path": "/home/user/Projects/main.cpp", "bytes": 1000000},
    {"path": "/home/user/Projects/utils.cpp", "bytes": 800000}
  ]
}
```
```

--------------------------------

### C++ API: FileFinder

Source: https://context7.com/0langa/universal-toolkit/llms.txt

The `FileFinder` class provides programmatic access to recursively search directories for files matching specified patterns or extensions, returning detailed file entry information.

```APIDOC
## C++ API: FileFinder - File Search

### Description
Recursively searches directories for files matching patterns or extensions. Returns `FileEntry` objects containing path, size, and modification time.

### Class
`toolkit::FileFinder`

### Methods
- `static std::vector<FileEntry> search(const fs::path& dir, const FileFinderOptions& options)`: Performs a search based on provided options.
- `static std::vector<FileEntry> by_extension(const fs::path& dir, const std::string& ext, bool recursive = true)`: Convenience method to search by extension.
- `static std::vector<FileEntry> by_pattern(const fs::path& dir, const std::string& pattern, bool recursive = true)`: Convenience method to search by glob pattern.

### `FileFinderOptions` Struct
- `std::string pattern`: Glob pattern for file names.
- `std::string extension`: File extension filter.
- `bool recursive`: Whether to search recursively.
- `bool skip_hidden`: Whether to skip hidden files.
- `uint64_t min_size`: Minimum file size in bytes.
- `uint64_t max_size`: Maximum file size in bytes.

### `FileEntry` Struct
- `fs::path path`: Path to the file.
- `uint64_t size`: Size of the file in bytes.
- `std::filesystem::file_time_type last_write_time`: Last modification time.

### Example Usage
```cpp
#include "toolkit/file_finder.hpp"
#include <iostream>

namespace fs = std::filesystem;
using namespace toolkit;

int main() {
    // Search with full options
    FileFinderOptions opts;
    opts.pattern = "*.cpp";
    opts.recursive = true;
    opts.skip_hidden = true;
    opts.min_size = 1024;  // >= 1 KiB
    opts.max_size = 0;     // no upper limit

    auto results = FileFinder::search("/path/to/project", opts);
    for (const auto& entry : results) {
        std::cout << entry.path.string()
                  << " (" << entry.size << " bytes)\n";
    }

    // Convenience: search by extension
    auto txtFiles = FileFinder::by_extension("/home/user/docs", ".txt");

    // Convenience: search by pattern
    auto reports = FileFinder::by_pattern("/data", "report_*.csv", true);

    return 0;
}
```
```

--------------------------------

### Find Large Files with LargeFileFinder (C++)

Source: https://context7.com/0langa/universal-toolkit/llms.txt

Scans directories for files exceeding a specified size threshold, sorting results by size in descending order. It supports recursive scanning, skipping hidden files, and limiting the number of results. The function requires 'toolkit/large_file_finder.hpp' and provides a human-readable format for file sizes. An overload allows specifying the threshold and recursion directly.

```cpp
#include "toolkit/large_file_finder.hpp"
#include <iostream>

using namespace toolkit;

int main() {
    LargeFileFinderOptions opts;
    opts.threshold_bytes = 100ULL * 1024 * 1024;  // 100 MiB
    opts.recursive = true;
    opts.skip_hidden = false;
    opts.max_results = 0;  // 0 = unlimited

    auto results = LargeFileFinder::scan("/home", opts);

    std::cout << "Large files (>= "
              << LargeFileFinder::human_readable(opts.threshold_bytes) << "):\n";

    for (const auto& entry : results) {
        std::cout << "  " << entry.size_string()
                  << "  " << entry.path.string() << "\n";
    }

    // Convenience overload with explicit threshold
    auto largeFiles = LargeFileFinder::scan("/var", 50 * 1024 * 1024, true);

    // Format bytes as human-readable
    std::string sizeStr = LargeFileFinder::human_readable(1073741824);  // "1.00 GiB"

    return 0;
}

```

--------------------------------

### Configure Universal Toolkit Static Library with CMake

Source: https://github.com/0langa/universal-toolkit/blob/main/src/modules/CMakeLists.txt

This CMake script defines a static library named 'toolkit_modules' using several C++ source files. It specifies include directories, enforces C++20 standard, and applies platform-specific compile options for enhanced code quality and portability.

```cmake
add_library(toolkit_modules STATIC
    file_finder.cpp
    duplicate_finder.cpp
    storage_analyzer.cpp
    file_organizer.cpp
    large_file_finder.cpp
)

target_include_directories(toolkit_modules PUBLIC
    ${PROJECT_SOURCE_DIR}/include
)

target_compile_features(toolkit_modules PUBLIC cxx_std_20)

if(UNIX)
    target_compile_options(toolkit_modules PRIVATE -Wall -Wextra -Wpedantic)
elseif(MSVC)
    target_compile_options(toolkit_modules PRIVATE /W4)
endif()
```

--------------------------------

### C++ DuplicateFinder API

Source: https://context7.com/0langa/universal-toolkit/llms.txt

Uses the DuplicateFinder class to scan directories for duplicate files based on FNV-1a 64-bit hashing. It calculates wasted space and provides grouped file lists.

```cpp
#include "toolkit/duplicate_finder.hpp"
#include <iostream>

using namespace toolkit;

int main() {
    DuplicateFinderOptions opts;
    opts.recursive = true;
    opts.skip_hidden = false;
    opts.min_size = 1;

    auto groups = DuplicateFinder::scan("/home/user/Downloads", opts);
    auto totalWasted = DuplicateFinder::total_wasted(groups);

    std::cout << "Found " << groups.size() << " duplicate groups\n";
    std::cout << "Total wasted: " << totalWasted << " bytes\n\n";

    for (const auto& group : groups) {
        std::cout << "Hash: " << group.hash << " | Size: " << group.size << " | Copies: " << group.files.size() << " | Wasted: " << group.wasted_bytes() << "\n";
        for (const auto& file : group.files) {
            std::cout << "  " << file.string() << "\n";
        }
    }

    std::string hash = DuplicateFinder::hash_file("/path/to/file.dat");

    return 0;
}
```

--------------------------------

### C++ FileFinder API

Source: https://context7.com/0langa/universal-toolkit/llms.txt

Utilizes the FileFinder class to perform recursive directory searches with specific filtering options. Returns FileEntry objects containing path, size, and metadata.

```cpp
#include "toolkit/file_finder.hpp"
#include <iostream>

namespace fs = std::filesystem;
using namespace toolkit;

int main() {
    FileFinderOptions opts;
    opts.pattern = "*.cpp";
    opts.recursive = true;
    opts.skip_hidden = true;
    opts.min_size = 1024;
    opts.max_size = 0;

    auto results = FileFinder::search("/path/to/project", opts);
    for (const auto& entry : results) {
        std::cout << entry.path.string() << " (" << entry.size << " bytes)\n";
    }

    auto txtFiles = FileFinder::by_extension("/home/user/docs", ".txt");
    auto reports = FileFinder::by_pattern("/data", "report_*.csv", true);

    return 0;
}
```

--------------------------------

### FileOrganizer - Automatic File Organization

Source: https://context7.com/0langa/universal-toolkit/llms.txt

Organizes files by moving or copying them into subdirectories based on extension or modification date. Features dry-run mode for previewing changes.

```APIDOC
## FileOrganizer - Automatic File Organization

### Description
Moves or copies files into organized subdirectories by extension or modification date. Supports dry-run mode for previewing operations.

### Method
N/A (This is a C++ library usage example)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```cpp
#include "toolkit/file_organizer.hpp"
#include <iostream>

using namespace toolkit;

int main() {
    FileOrganizerOptions opts;
    opts.strategy = OrganizeStrategy::ByExtension;
    opts.copy_instead_of_move = false;
    opts.dry_run = true;
    opts.overwrite_existing = false;
    opts.no_extension_folder = "other";

    auto operations = FileOrganizer::organize(
        "/home/user/Downloads",
        "/home/user/Sorted",
        opts
    );

    std::cout << (opts.dry_run ? "[DRY RUN] " : "")
              << "Operations: " << operations.size() << "\n\n";

    for (const auto& op : operations) {
        std::cout << op.source.filename().string()
                  << " -> " << op.destination.string();
        if (!op.error.empty()) {
            std::cout << " [ERROR: " << op.error << "]";
        }
        if (op.was_executed) {
            std::cout << " [DONE]";
        }
        std::cout << "\n";
    }

    opts.dry_run = false;
    auto results = FileOrganizer::organize(
        "/home/user/Downloads",
        "/home/user/Sorted",
        opts
    );

    return 0;
}
```

### Response
#### Success Response (200)
- **operations** (vector<FileOperationResult>) - A list of file operations performed or planned.

#### Response Example
```json
[
  {
    "source": "/home/user/Downloads/document.pdf",
    "destination": "/home/user/Sorted/pdf/document.pdf",
    "error": "",
    "was_executed": true
  },
  {
    "source": "/home/user/Downloads/image.jpg",
    "destination": "/home/user/Sorted/jpg/image.jpg",
    "error": "File already exists",
    "was_executed": false
  }
]
```
```

--------------------------------

### C++ API: DuplicateFinder

Source: https://context7.com/0langa/universal-toolkit/llms.txt

The `DuplicateFinder` class enables programmatic identification of duplicate files based on content hashing, providing detailed information about duplicate groups and wasted space.

```APIDOC
## C++ API: DuplicateFinder - Duplicate Detection

### Description
Identifies duplicate files using FNV-1a 64-bit content hashing. Returns `DuplicateGroup` objects containing file lists, size, hash, and wasted space calculations.

### Class
`toolkit::DuplicateFinder`

### Methods
- `static std::vector<DuplicateGroup> scan(const fs::path& dir, const DuplicateFinderOptions& options)`: Scans a directory for duplicate files.
- `static uint64_t total_wasted(const std::vector<DuplicateGroup>& groups)`: Calculates the total wasted space from a list of duplicate groups.
- `static std::string hash_file(const fs::path& file_path)`: Computes the FNV-1a 64-bit hash for a single file.

### `DuplicateFinderOptions` Struct
- `bool recursive`: Whether to search recursively.
- `bool skip_hidden`: Whether to skip hidden files.
- `uint64_t min_size`: Minimum file size in bytes to consider.

### `DuplicateGroup` Struct
- `std::string hash`: The content hash of the duplicate files.
- `uint64_t size`: The size of each file in the group.
- `std::vector<fs::path> files`: A list of paths to the duplicate files.
- `uint64_t wasted_bytes() const`: Calculates the wasted space for this group.

### Example Usage
```cpp
#include "toolkit/duplicate_finder.hpp"
#include <iostream>

using namespace toolkit;

int main() {
    DuplicateFinderOptions opts;
    opts.recursive = true;
    opts.skip_hidden = false;
    opts.min_size = 1;  // ignore 0-byte files

    auto groups = DuplicateFinder::scan("/home/user/Downloads", opts);
    auto totalWasted = DuplicateFinder::total_wasted(groups);

    std::cout << "Found " << groups.size() << " duplicate groups\n";
    std::cout << "Total wasted: " << totalWasted << " bytes\n\n";

    for (const auto& group : groups) {
        std::cout << "Hash: " << group.hash
                  << " | Size: " << group.size
                  << " | Copies: " << group.files.size()
                  << " | Wasted: " << group.wasted_bytes() << "\n";
        for (const auto& file : group.files) {
            std::cout << "  " << file.string() << "\n";
        }
    }

    // Compute hash for a single file
    std::string hash = DuplicateFinder::hash_file("/path/to/file.dat");

    return 0;
}
```
```

--------------------------------

### LargeFileFinder - Large File Discovery

Source: https://context7.com/0langa/universal-toolkit/llms.txt

Scans directories for files exceeding a specified size threshold. Results are sorted by size in descending order.

```APIDOC
## LargeFileFinder - Large File Discovery

### Description
Scans directories for files exceeding a size threshold. Results are sorted by size descending for immediate visibility of largest consumers.

### Method
N/A (This is a C++ library usage example)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **path** (string) - Required - The directory to scan.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```cpp
#include "toolkit/large_file_finder.hpp"
#include <iostream>

using namespace toolkit;

int main() {
    LargeFileFinderOptions opts;
    opts.threshold_bytes = 100ULL * 1024 * 1024;  // 100 MiB
    opts.recursive = true;
    opts.skip_hidden = false;
    opts.max_results = 0;

    auto results = LargeFileFinder::scan("/home", opts);

    std::cout << "Large files (>= "
              << LargeFileFinder::human_readable(opts.threshold_bytes) << "):\n";

    for (const auto& entry : results) {
        std::cout << "  " << entry.size_string()
                  << "  " << entry.path.string() << "\n";
    }

    auto largeFiles = LargeFileFinder::scan("/var", 50 * 1024 * 1024, true);

    std::string sizeStr = LargeFileFinder::human_readable(1073741824);  // "1.00 GiB"

    return 0;
}
```

### Response
#### Success Response (200)
- **results** (vector<LargeFileEntry>) - A list of files exceeding the size threshold, sorted by size descending.

#### Response Example
```json
[
  {
    "path": "/home/user/large_video.mp4",
    "bytes": 5000000000,
    "size_string": "4.66 GiB"
  },
  {
    "path": "/home/user/big_archive.zip",
    "bytes": 1500000000,
    "size_string": "1.40 GiB"
  }
]
```
```
Tokens:
Raw