Module fs 

File system utilities for cross-platform file operations

This module provides safe, atomic file operations designed to work consistently across Windows, macOS, and Linux. All functions handle platform-specific differences such as path lengths, permissions, and separators.

Key Features

• Atomic operations: Files are written atomically to prevent corruption
• Cross-platform: Handles Windows long paths, Unix permissions, and path separators
• Parallel operations: Async versions for processing multiple files concurrently
• Safety: Path traversal prevention and safe path handling
• Checksum validation: SHA-256 checksums for data integrity

Examples

use agpm_cli::utils::fs::{ensure_dir, safe_write, calculate_checksum};
use std::path::Path;

// Create directory structure
ensure_dir(Path::new("output/agents"))?;

// Write file atomically
safe_write(Path::new("output/config.toml"), "[sources]")?;

// Verify file integrity
let checksum = calculate_checksum(Path::new("output/config.toml"))?;
println!("File checksum: {}", checksum);

Platform Considerations

Windows

• Supports long paths (>260 characters) using UNC prefixes
• Handles case-insensitive file systems
• Manages file permissions and attributes correctly

Unix/Linux

• Preserves file permissions during copy operations
• Handles case-sensitive file systems
• Supports symbolic links appropriately

macOS

• Handles HFS+ case-insensitive by default
• Supports extended attributes
• Works with case-sensitive APFS volumes

Structs

TempDir

A temporary directory that automatically cleans up when dropped.

Functions

atomic_write

Atomically writes bytes to a file using a write-then-rename strategy.

atomic_write_multiple

Writes multiple files atomically in parallel.

calculate_checksum

Calculates the SHA-256 checksum of a file.

calculate_checksums_parallel

Calculates SHA-256 checksums for multiple files concurrently.

compare_file_times

Compares the modification times of two files.

copy_dir

Recursively copies a directory and all its contents to a new location.

copy_dir_all

Copy a directory recursively (alias for consistency)

copy_dirs_parallel

Copies multiple directories concurrently.

copy_files_parallel

Copies multiple files concurrently using parallel processing.

create_temp_file

Creates a temporary file with content for testing.

dir_size

Calculates the total size of a directory and all its contents recursively.

ensure_dir

Ensures a directory exists, creating it and all parent directories if necessary.

ensure_dir_exists

Alias for ensure_dir for consistency

ensure_parent_dir

Ensures that the parent directory of a file path exists.

file_exists_and_readable

Checks if a file exists and is readable.

find_files

Recursively finds files matching a pattern in a directory tree.

find_project_root

Finds the AGPM project root by searching for agpm.toml in the directory hierarchy.

get_directory_size

Asynchronously calculates the total size of a directory and all its contents.

get_global_config_path

Returns the path to the global AGPM configuration file.

get_modified_time

Gets the modification time of a file.

is_safe_path

Checks if a path is safe and doesn’t escape the base directory.

normalize_path

Normalizes a path by resolving . and .. components.

read_files_parallel

Reads multiple files concurrently and returns their contents.

read_json_file

Reads and parses a JSON file.

read_text_file

Reads a text file with proper error handling and context.

read_toml_file

Reads and parses a TOML file.

read_yaml_file

Reads and parses a YAML file.

remove_dir_all

Recursively removes a directory and all its contents.

safe_write

Safely writes a string to a file using atomic operations.

write_json_file

Writes data as JSON to a file atomically.

write_text_file

Writes a text file atomically with proper error handling.

write_toml_file

Writes data as TOML to a file atomically.

write_yaml_file

Writes data as YAML to a file atomically.