Module utils 

Cross-platform utilities and helpers

This module provides utility functions for file operations, platform-specific code, and user interface elements like progress bars. All utilities are designed to work consistently across Windows, macOS, and Linux.

Modules

• fs - File system operations with atomic writes and safe copying
• manifest_utils - Utilities for loading and validating manifests
• platform - Platform-specific helpers and path resolution
• progress - Multi-phase progress tracking for long-running operations

Cross-Platform Considerations

All utilities handle platform differences:

• Path separators (/ vs \)
• Line endings (\n vs \r\n)
• File permissions and attributes
• Shell commands and environment variables

Example

use agpm_cli::utils::{ensure_dir, atomic_write, MultiPhaseProgress, InstallationPhase};
use std::path::Path;

// Ensure directory exists
ensure_dir(Path::new("output/agents"))?;

// Write file atomically
atomic_write(Path::new("output/config.toml"), b"content")?;

// Show progress with phases
let progress = MultiPhaseProgress::new(true);
progress.start_phase(InstallationPhase::Installing, Some("Processing files"));

Re-exports

pub use fs::atomic_write;

pub use fs::compare_file_times;

pub use fs::copy_dir;

pub use fs::create_temp_file;

pub use fs::ensure_dir;

pub use fs::file_exists_and_readable;

pub use fs::get_modified_time;

pub use fs::normalize_path;

pub use fs::read_json_file;

pub use fs::read_text_file;

pub use fs::read_toml_file;

pub use fs::read_yaml_file;

pub use fs::safe_write;

pub use fs::write_json_file;

pub use fs::write_text_file;

pub use fs::write_toml_file;

pub use fs::write_yaml_file;

pub use manifest_utils::load_and_validate_manifest;

pub use manifest_utils::load_project_manifest;

pub use manifest_utils::manifest_exists;

pub use manifest_utils::manifest_path;

pub use path_validation::ensure_directory_exists;

pub use path_validation::ensure_within_directory;

pub use path_validation::find_project_root;

pub use path_validation::safe_canonicalize;

pub use path_validation::safe_relative_path;

pub use path_validation::sanitize_file_name;

pub use path_validation::validate_no_traversal;

pub use path_validation::validate_project_path;

pub use path_validation::validate_resource_path;

pub use platform::compute_relative_install_path;

pub use platform::get_git_command;

pub use platform::get_home_dir;

pub use platform::is_windows;

pub use platform::normalize_path_for_storage;

pub use platform::resolve_path;

pub use progress::InstallationPhase;

pub use progress::MultiPhaseProgress;

pub use progress::collect_dependency_names;

Modules

fs

File system utilities for cross-platform file operations

manifest_utils

Utilities for working with manifest files

path_validation

Path validation and security utilities for AGPM.

platform

Platform-specific utilities and cross-platform compatibility helpers

progress

Progress indicators and user interface utilities

security

Security utilities for path validation and access control

Statics

EMPTY_VARIANT_INPUTS_HASH

SHA-256 hash of an empty JSON object {}. This is the default hash when there are no template variables. Computed lazily to ensure consistency with the hash function.

Functions

canonicalize_json

Canonicalize JSON for deterministic hashing.

compute_relative_path

Computes a relative path from a base directory to a target path.

compute_variant_inputs_hash

Compute SHA-256 hash of variant_inputs JSON value.

generate_backup_path

Generates a backup path for tool configuration files.

is_git_url

Determines if a given URL is a Git repository URL (including file:// URLs).

is_local_path

Determines if a given URL/path is a local filesystem path (not a Git repository URL).

resolve_file_relative_path

Resolves a file-relative path from a transitive dependency.

resolve_path_relative_to_manifest

Resolves a path relative to the manifest directory.