agpm_cli/utils/fs/
mod.rs

1//! File system utilities for cross-platform file operations
2//!
3//! This module provides safe, atomic file operations designed to work consistently
4//! across Windows, macOS, and Linux. All functions handle platform-specific
5//! differences such as path lengths, permissions, and separators.
6//!
7//! # Key Features
8//!
9//! - **Atomic operations**: Files are written atomically to prevent corruption
10//! - **Cross-platform**: Handles Windows long paths, Unix permissions, and path separators
11//! - **Parallel operations**: Async versions for processing multiple files concurrently
12//! - **Safety**: Path traversal prevention and safe path handling
13//! - **Checksum validation**: SHA-256 checksums for data integrity
14//!
15//! # Examples
16//!
17//! ```rust,no_run
18//! use agpm_cli::utils::fs::{ensure_dir, safe_write, calculate_checksum};
19//! use std::path::Path;
20//!
21//! # fn example() -> anyhow::Result<()> {
22//! // Create directory structure
23//! ensure_dir(Path::new("output/agents"))?;
24//!
25//! // Write file atomically
26//! safe_write(Path::new("output/config.toml"), "[sources]")?;
27//!
28//! // Verify file integrity
29//! let checksum = calculate_checksum(Path::new("output/config.toml"))?;
30//! println!("File checksum: {}", checksum);
31//! # Ok(())
32//! # }
33//! ```
34//!
35//! # Platform Considerations
36//!
37//! ## Windows
38//! - Supports long paths (>260 characters) using UNC prefixes
39//! - Handles case-insensitive file systems
40//! - Manages file permissions and attributes correctly
41//!
42//! ## Unix/Linux
43//! - Preserves file permissions during copy operations
44//! - Handles case-sensitive file systems
45//! - Supports symbolic links appropriately
46//!
47//! ## macOS
48//! - Handles HFS+ case-insensitive by default
49//! - Supports extended attributes
50//! - Works with case-sensitive APFS volumes
51
52// Module declarations
53pub mod atomic;
54pub mod dirs;
55pub mod discovery;
56pub mod formats;
57pub mod metadata;
58pub mod parallel;
59pub mod paths;
60pub mod temp;
61
62// Re-export commonly used items from each module
63
64// Directory operations
65pub use dirs::{
66    copy_dir, copy_dir_all, ensure_dir, ensure_dir_exists, ensure_parent_dir, remove_dir_all,
67};
68
69// Atomic write operations
70pub use atomic::{atomic_write, atomic_write_multiple, safe_write};
71
72// Path utilities
73pub use paths::{find_project_root, get_global_config_path, is_safe_path, normalize_path};
74
75// File discovery
76pub use discovery::find_files;
77
78// Temporary directories
79pub use temp::TempDir;
80
81// Metadata operations
82pub use metadata::{
83    calculate_checksum, calculate_checksums_parallel, compare_file_times, dir_size,
84    file_exists_and_readable, get_directory_size, get_modified_time,
85};
86
87// Parallel operations
88pub use parallel::{copy_dirs_parallel, copy_files_parallel, read_files_parallel};
89
90// Format-specific I/O
91pub use formats::{
92    create_temp_file, read_json_file, read_text_file, read_text_file_with_retry, read_toml_file,
93    read_yaml_file, write_json_file, write_text_file, write_toml_file, write_yaml_file,
94};
agpm_cli/utils/fs/mod.rs

agpm_cli/utils/fs/
mod.rs
